deploy: ef1cdb59ac

api/basic_json/to_bjdata.md

@@ -212,4 +212,6 @@ Linear in the size of the JSON value `j`.
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
-  array or object was silently skipped, producing invalid BJData.
+  array or object was silently skipped, producing invalid BJData.
+- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were
+  silently truncated to 64 bits.

api/basic_json/to_bjdata/index.html

@@ -103,4 +103,4 @@
 <span class=w>    </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=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.o</span><span class=kc>t</span><span class=err>her_error.</span><span class=mi>502</span><span class=p>]</span><span class=w> </span><span class=err>use_</span><span class=kc>t</span><span class=err>ype</span><span class=w> </span><span class=err>requires</span><span class=w> </span><span class=err>use_size</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=kc>true</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bjdata/ >from_bjdata</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary JData">BJData</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.11.0.</li> <li><abbr title="Binary JData">BJData</abbr> version parameter (for draft3 binary encoding) added in version 3.12.0.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid <abbr title="Binary JData">BJData</abbr>.</li> </ul> <!-- 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 6, 2026 05:33:34 UTC">October 6, 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 &copy; 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.8Line truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bjdata/ >from_bjdata</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary JData">BJData</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.11.0.</li> <li><abbr title="Binary JData">BJData</abbr> version parameter (for draft3 binary encoding) added in version 3.12.0.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid <abbr title="Binary JData">BJData</abbr>.</li> <li>Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, they were silently truncated to 64 bits.</li> </ul> <!-- 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 21, 2026 08:36:31 UTC">October 21, 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 &copy; 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-Line truncated

api/basic_json/to_bjdata/index.md

@@ -189,3 +189,4 @@ Output:
 - BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid BJData.
+- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0 unreleased; previously, they were silently truncated to 64 bits.

api/basic_json/to_bon8.md

@@ -37,8 +37,9 @@ With (2), the bytes written before the exception remain in the output adapter.
 
 ## Exceptions
 
-- Throws [out_of_range.407](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an unsigned integer
-  above 9223372036854775807, which BON8 cannot represent
+- Throws [out_of_range.407](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer outside
+  the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any
+  integer beyond int64), which BON8 cannot represent
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if `j` contains a string that is not
   valid UTF-8
 - Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is

api/basic_json/to_bon8/index.html

@@ -4,7 +4,7 @@
 <span class=c1>// (2)</span>
 <span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_bon8</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>output_adapter</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>&gt;</span><span class=w> </span><span class=n>o</span><span class=p>);</span>
 <span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_bon8</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>output_adapter</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span><span class=w> </span><span class=n>o</span><span class=p>);</span>
-</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the <abbr title="Binary Object Notation 8">BON8</abbr> (Binary Object Notation 8) serialization format. <abbr title="Binary Object Notation 8">BON8</abbr> is a compact binary serialization format that stores strings as <abbr title="Unicode Transformation Format">UTF</abbr>-8 without a length prefix.</p> <ol> <li>Returns a byte vector containing the <abbr title="Binary Object Notation 8">BON8</abbr> serialization.</li> <li>Writes the <abbr title="Binary Object Notation 8">BON8</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bon8/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Binary Object Notation 8">BON8</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>, which is never modified. With (2), the bytes written before the exception remain in the output adapter.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range407>out_of_range.407</a> if <code>j</code> contains an unsigned integer above 9223372036854775807, which <abbr title="Binary Object Notation 8">BON8</abbr> cannot represent</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if <code>j</code> contains a string that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to BON8"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: serialize a <abbr title="JavaScript Object Notation">JSON</abbr> value to <abbr title="Binary Object Notation 8">BON8</abbr></summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in <abbr title="Binary Object Notation 8">BON8</abbr> format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
+</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the <abbr title="Binary Object Notation 8">BON8</abbr> (Binary Object Notation 8) serialization format. <abbr title="Binary Object Notation 8">BON8</abbr> is a compact binary serialization format that stores strings as <abbr title="Unicode Transformation Format">UTF</abbr>-8 without a length prefix.</p> <ol> <li>Returns a byte vector containing the <abbr title="Binary Object Notation 8">BON8</abbr> serialization.</li> <li>Writes the <abbr title="Binary Object Notation 8">BON8</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bon8/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Binary Object Notation 8">BON8</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>, which is never modified. With (2), the bytes written before the exception remain in the output adapter.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range407>out_of_range.407</a> if <code>j</code> contains an integer outside the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any integer beyond int64), which <abbr title="Binary Object Notation 8">BON8</abbr> cannot represent</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if <code>j</code> contains a string that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to BON8"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: serialize a <abbr title="JavaScript Object Notation">JSON</abbr> value to <abbr title="Binary Object Notation 8">BON8</abbr></summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in <abbr title="Binary Object Notation 8">BON8</abbr> format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -50,4 +50,4 @@
 <span class=w>    </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=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.</span><span class=kc>t</span><span class=err>ype_error.</span><span class=mi>316</span><span class=p>]</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>valid</span><span class=w> </span><span class=err>UTF</span><span class=mi>-8</span><span class=w> </span><span class=err>by</span><span class=kc>te</span><span class=w> </span><span class=err>a</span><span class=kc>t</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>dex</span><span class=w> </span><span class=mi>0</span><span class=p>:</span><span class=w> </span><span class=mi>0</span><span class=err>xFF</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bon8/ >from_bon8</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary Object Notation 8">BON8</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- 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 11, 2026 06:22:00 UTC">October 11, 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 &copy; 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/" tLine truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bon8/ >from_bon8</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary Object Notation 8">BON8</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- 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 21, 2026 08:36:31 UTC">October 21, 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 &copy; 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/" tLine truncated

api/basic_json/to_bon8/index.md

@@ -33,7 +33,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
-- Throws [out_of_range.407](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an unsigned integer above 9223372036854775807, which BON8 cannot represent
+- Throws [out_of_range.407](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any integer beyond int64), which BON8 cannot represent
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `j` contains a string that is not valid UTF-8
 - Throws [type_error.321](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error321) if `j` or a value nested in it is discarded; example: `"cannot serialize discarded value to BON8"`
 

api/basic_json/to_bson.md

@@ -47,6 +47,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [`type_error.317`](../../home/exceptions.md#jsonexceptiontype_error317) if the top-level type of the JSON value
   is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains a signed integer
+  outside the range of int64 or an unsigned integer outside the range of uint64, which is only possible with a number
+  type wider than 64 bits; example:
+  `"integer number 9223372036854775808 cannot be represented by BSON as it does not fit int64"`
 - Throws [`out_of_range.409`](../../home/exceptions.md#jsonexceptionout_of_range409) if a key in the JSON object contains
   a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
 - Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a document, array,
@@ -166,3 +170,5 @@ pass before anything is written.
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316` before anything
   is written.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_bson/index.html

@@ -7,7 +7,7 @@
 <span class=w>                    </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
 <span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_bson</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>output_adapter</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span><span class=w> </span><span class=n>o</span><span class=p>,</span>
 <span class=w>                    </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
-</code></pre></div> <p><abbr title="Binary JSON">BSON</abbr> (Binary <abbr title="JavaScript Object Notation">JSON</abbr>) is a binary format in which zero or more ordered key/value pairs are stored as a single entity (a so-called document).</p> <ol> <li>Returns a byte vector containing the <abbr title="Binary JSON">BSON</abbr> serialization.</li> <li>Writes the <abbr title="Binary JSON">BSON</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bson/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_bson</code> did before this parameter was added; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. If <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled, the default is <code>strict</code> instead.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Binary JSON">BSON</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error317><code>type_error.317</code></a> if the top-level type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; example: <code>"to serialize to BSON, top-level type must be object, but is string"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range409><code>out_of_range.409</code></a> if a key in the <abbr title="JavaScript Object Notation">JSON</abbr> object contains a null byte (code point U+0000); example: <code>"BSON key cannot contain code point U+0000 (at byte 2)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range412><code>out_of_range.412</code></a> if the length of a document, array, string, or binary value exceeds the range of the 32-bit <abbr title="Binary JSON">BSON</abbr> length field; example: <code>"BSON length 2147483661 exceeds maximum of 2147483647"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range415><code>out_of_range.415</code></a> if the subtype of a binary value exceeds 255, the maximum of the <abbr title="Binary JSON">BSON</abbr> binary subtype; example: <code>"subtype 70000 is too large for the BSON binary subtype (max 255)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code> (the default only if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if a value nested in <code>j</code> is discarded (the top-level value itself is covered by <code>type_error.317</code> above, since it must be an object); example: <code>"cannot serialize discarded value to BSON"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>. The length prefixes of all nested documents and arrays are computed in one pass before anything is written.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: serialize a <abbr title="JavaScript Object Notation">JSON</abbr> value to <abbr title="Binary JSON">BSON</abbr></summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in <abbr title="Binary JSON">BSON</abbr> format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;ioLine truncated
+</code></pre></div> <p><abbr title="Binary JSON">BSON</abbr> (Binary <abbr title="JavaScript Object Notation">JSON</abbr>) is a binary format in which zero or more ordered key/value pairs are stored as a single entity (a so-called document).</p> <ol> <li>Returns a byte vector containing the <abbr title="Binary JSON">BSON</abbr> serialization.</li> <li>Writes the <abbr title="Binary JSON">BSON</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bson/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_bson</code> did before this parameter was added; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. If <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled, the default is <code>strict</code> instead.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Binary JSON">BSON</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error317><code>type_error.317</code></a> if the top-level type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; example: <code>"to serialize to BSON, top-level type must be object, but is string"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range407><code>out_of_range.407</code></a> if <code>j</code> contains a signed integer outside the range of int64 or an unsigned integer outside the range of uint64, which is only possible with a number type wider than 64 bits; example: <code>"integer number 9223372036854775808 cannot be represented by BSON as it does not fit int64"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range409><code>out_of_range.409</code></a> if a key in the <abbr title="JavaScript Object Notation">JSON</abbr> object contains a null byte (code point U+0000); example: <code>"BSON key cannot contain code point U+0000 (at byte 2)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range412><code>out_of_range.412</code></a> if the length of a document, array, string, or binary value exceeds the range of the 32-bit <abbr title="Binary JSON">BSON</abbr> length field; example: <code>"BSON length 2147483661 exceeds maximum of 2147483647"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range415><code>out_of_range.415</code></a> if the subtype of a binary value exceeds 255, the maximum of the <abbr title="Binary JSON">BSON</abbr> binary subtype; example: <code>"subtype 70000 is too large for the BSON binary subtype (max 255)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code> (the default only if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if a value nested in <code>j</code> is discarded (the top-level value itself is covered by <code>type_error.317</code> above, since it must be an object); example: <code>"cannot serialize discarded value to BSON"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>. The length prefixes of all nested documents and arrays are computed in one pass before anything is written.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: seLine truncated
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -54,4 +54,4 @@
 <span class=w>    </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=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>409</span><span class=p>]</span><span class=w> </span><span class=err>BSON</span><span class=w> </span><span class=err>key</span><span class=w> </span><span class=err>ca</span><span class=kc>nn</span><span class=err>o</span><span class=kc>t</span><span class=w> </span><span class=err>co</span><span class=kc>nta</span><span class=err>i</span><span class=kc>n</span><span class=w> </span><span class=err>code</span><span class=w> </span><span class=err>poi</span><span class=kc>nt</span><span class=w> </span><span class=err>U+</span><span class=mi>0000</span><span class=w> </span><span class=err>(a</span><span class=kc>t</span><span class=w> </span><span class=err>by</span><span class=kc>te</span><span class=w> </span><span class=mi>2</span><span class=err>)</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bson/ >from_bson</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary JSON">BSON</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.4.0.</li> <li>Throws <code>out_of_range.412</code> and <code>out_of_range.415</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Linear in the size of <code>j</code>, and no longer limited by the call stack for deeply nested values, since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>out_of_range.415</code> is now detected before anything is written, like the other exceptions above, since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Throws <code>type_error.321</code> for a discarded value nested in <code>j</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, it was silently skipped, producing a document whose declared size did not match what was actually written.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code> before anything is written.</li> </ul> <!-- 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 6, 2026 05:33:34 UTC">October 6, 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 &copy; 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 LiLine truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_bson/ >from_bson</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Binary JSON">BSON</abbr> format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.4.0.</li> <li>Throws <code>out_of_range.412</code> and <code>out_of_range.415</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Linear in the size of <code>j</code>, and no longer limited by the call stack for deeply nested values, since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>out_of_range.415</code> is now detected before anything is written, like the other exceptions above, since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Throws <code>type_error.321</code> for a discarded value nested in <code>j</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, it was silently skipped, producing a document whose declared size did not match what was actually written.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code> before anything is written.</li> <li>Throws <code>out_of_range.407</code> for integers that do not fit 64 bits since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, integers of a number type wider than 64 bits were silently truncated.</li> </ul> <!-- 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 21, 2026 08:36:31 UTC">October 21, 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 &copy; 201Line truncated

api/basic_json/to_bson/index.md

@@ -39,6 +39,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 ## Exceptions
 
 - Throws [`type_error.317`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error317) if the top-level type of the JSON value is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains a signed integer outside the range of int64 or an unsigned integer outside the range of uint64, which is only possible with a number type wider than 64 bits; example: `"integer number 9223372036854775808 cannot be represented by BSON as it does not fit int64"`
 - Throws [`out_of_range.409`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range409) if a key in the JSON object contains a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
 - Throws [`out_of_range.412`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range412) if the length of a document, array, string, or binary value exceeds the range of the 32-bit BSON length field; example: `"BSON length 2147483661 exceeds maximum of 2147483647"`
 - Throws [`out_of_range.415`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range415) if the subtype of a binary value exceeds 255, the maximum of the BSON binary subtype; example: `"subtype 70000 is too large for the BSON binary subtype (max 255)"`
@@ -139,3 +140,4 @@ Output:
 - `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0 unreleased.
 - Throws `type_error.321` for a discarded value nested in `j` since version 3.13.0 unreleased; previously, it was silently skipped, producing a document whose declared size did not match what was actually written.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316` before anything is written.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/basic_json/to_cbor.md

@@ -46,6 +46,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer
+  outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example:
+  `"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]"`
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
@@ -113,3 +116,5 @@ Linear in the size of the JSON value `j`.
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
   array or object was silently skipped, producing invalid CBOR.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_cbor/index.html

@@ -7,7 +7,7 @@
 <span class=w>                     </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
 <span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_cbor</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>output_adapter</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span><span class=w> </span><span class=n>o</span><span class=p>,</span>
 <span class=w>                     </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
-</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the <abbr title="Concise Binary Object Representation">CBOR</abbr> (Concise Binary Object Representation) serialization format. <abbr title="Concise Binary Object Representation">CBOR</abbr> is a binary serialization format that aims to be more compact than <abbr title="JavaScript Object Notation">JSON</abbr> itself, yet more efficient to parse.</p> <ol> <li>Returns a byte vector containing the <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization.</li> <li>Writes the <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/cbor/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_cbor</code> did before this parameter was added; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. If <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled, the default is <code>strict</code> instead.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Concise Binary Object Representation">CBOR</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key in <code>j</code> is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code> (the default only if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to CBOR"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in <abbr title="Concise Binary Object Representation">CBOR</abbr> format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
+</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the <abbr title="Concise Binary Object Representation">CBOR</abbr> (Concise Binary Object Representation) serialization format. <abbr title="Concise Binary Object Representation">CBOR</abbr> is a binary serialization format that aims to be more compact than <abbr title="JavaScript Object Notation">JSON</abbr> itself, yet more efficient to parse.</p> <ol> <li>Returns a byte vector containing the <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization.</li> <li>Writes the <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/cbor/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_cbor</code> did before this parameter was added; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. If <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled, the default is <code>strict</code> instead.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="Concise Binary Object Representation">CBOR</abbr> serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range407><code>out_of_range.407</code></a> if <code>j</code> contains an integer outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example: <code>"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key in <code>j</code> is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code> (the default only if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to CBOR"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in <abbr title="Concise Binary Object Representation">CBOR</abbr> format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -30,4 +30,4 @@
 <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>&lt;&lt;</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=p>}</span>
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>0</span><span class=err>xa</span><span class=mi>2</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>67</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>63</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>6</span><span class=kc>f</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>6</span><span class=err>d</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>70</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>61</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>63</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>74</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=kc>f</span><span class=mi>5</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>66</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>73</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>63</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>68</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>65</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>6</span><span class=err>d</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>61</span><span class=w> </span><span class=mi>0</span><span class=err>x</span><span class=mi>00</span><span class=w> </span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_cbor/ >from_cbor</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 2.0.9.</li> <li>Compact representation of floating-point numbers added in version 3.8.0.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid <abbr title="Concise Binary Object Representation">CBOR</abbr>.</li> </ul> <!-- 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 6, 2026 05:33:34 UTC">October 6, 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 &copy; 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.Line truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_cbor/ >from_cbor</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> <li><a href=../to_msgpack/ >to_msgpack</a> create a MessagePack serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 2.0.9.</li> <li>Compact representation of floating-point numbers added in version 3.8.0.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before; <code>strict</code> (the default if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled) throws <code>type_error.316</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid <abbr title="Concise Binary Object Representation">CBOR</abbr>.</li> <li>Throws <code>out_of_range.407</code> for integers that do not fit 64 bits since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, integers of a number type wider than 64 bits were silently truncated.</li> </ul> <!-- 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 21, 2026 08:36:31 UTC">October 21, 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 &copy; 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-Line truncated

api/basic_json/to_cbor/index.md

@@ -38,6 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example: `"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]"`
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string or object key in `j` is not valid UTF-8 and `error_handler` is `strict` (the default only if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled)
 - Throws [type_error.321](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error321) if `j` or a value nested in it is discarded; example: `"cannot serialize discarded value to CBOR"`
 
@@ -97,3 +98,4 @@ Output:
 - Compact representation of floating-point numbers added in version 3.8.0.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid CBOR.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/basic_json/to_msgpack.md

@@ -46,6 +46,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer
+  outside [-2^63, 2^64-1], which is only possible with a number type wider than 64 bits; example:
+  `"integer number 18446744073709551616 cannot be represented by MessagePack as it does not fit [-2^63, 2^64-1]"`
 - Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a string, binary
   value, array, or object exceeds 4294967295, the maximum MessagePack can store; example:
   `"MessagePack length 4294967296 exceeds maximum of 4294967295"`
@@ -156,3 +159,5 @@ Linear in the size of the JSON value `j`.
   `number_unsigned_t`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
   array or object was silently skipped, producing invalid MessagePack.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_msgpack/index.html

@@ -7,7 +7,7 @@
 <span class=w>                       </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
 <span class=k>static</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_msgpack</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>detail</span><span class=o>::</span><span class=n>output_adapter</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span><span class=w> </span><span class=n>o</span><span class=p>,</span>
 <span class=w>                       </span><span class=k>const</span><span class=w> </span><span class=n>error_handler_t</span><span class=w> </span><span class=n>error_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>error_handler_t</span><span class=o>::</span><span class=n>keep</span><span class=p>);</span>
-</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the MessagePack serialization format. MessagePack is a binary serialization format that aims to be more compact than <abbr title="JavaScript Object Notation">JSON</abbr> itself, yet more efficient to parse.</p> <ol> <li>Returns a byte vector containing the MessagePack serialization.</li> <li>Writes the MessagePack serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/messagepack/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_msgpack</code> did before this parameter was added and as the MessagePack specification allows; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. Unlike the other binary writers, the default stays <code>keep</code> even if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>MessagePack serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range412><code>out_of_range.412</code></a> if the length of a string, binary value, array, or object exceeds 4294967295, the maximum MessagePack can store; example: <code>"MessagePack length 4294967296 exceeds maximum of 4294967295"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range415><code>out_of_range.415</code></a> if the subtype of a binary value exceeds 255, the maximum of the MessagePack ext type; example: <code>"subtype 70000 is too large for the MessagePack ext type (max 255)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key in <code>j</code> is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to MessagePack"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: serialize a <abbr title="JavaScript Object Notation">JSON</abbr> value to MessagePack</summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in MessagePack format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
+</code></pre></div> <p>Serializes a given <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code> to a byte vector using the MessagePack serialization format. MessagePack is a binary serialization format that aims to be more compact than <abbr title="JavaScript Object Notation">JSON</abbr> itself, yet more efficient to parse.</p> <ol> <li>Returns a byte vector containing the MessagePack serialization.</li> <li>Writes the MessagePack serialization to an output adapter.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/messagepack/ >dedicated page</a>.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>j</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to serialize</dd> <dt><code>o</code> (in)</dt> <dd>output adapter to write serialization to</dd> <dt><code>error_handler</code> (in)</dt> <dd>how to treat a string or object key in <code>j</code> that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8; see <a href=../error_handler_t/ ><code>error_handler_t</code></a>. The default, <code>keep</code>, writes the ill-formed bytes to the output as is, as every version of <code>to_msgpack</code> did before this parameter was added and as the MessagePack specification allows; <code>strict</code> throws; <code>replace</code>/<code>ignore</code> sanitize it the same way <a href=../dump/ ><code>dump</code></a> would. Unlike the other binary writers, the default stays <code>keep</code> even if <a href=../../macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled.</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>MessagePack serialization as a byte vector</li> <li>(none)</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range407><code>out_of_range.407</code></a> if <code>j</code> contains an integer outside [-2^63, 2^64-1], which is only possible with a number type wider than 64 bits; example: <code>"integer number 18446744073709551616 cannot be represented by MessagePack as it does not fit [-2^63, 2^64-1]"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range412><code>out_of_range.412</code></a> if the length of a string, binary value, array, or object exceeds 4294967295, the maximum MessagePack can store; example: <code>"MessagePack length 4294967296 exceeds maximum of 4294967295"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range415><code>out_of_range.415</code></a> if the subtype of a binary value exceeds 255, the maximum of the MessagePack ext type; example: <code>"subtype 70000 is too large for the MessagePack ext type (max 255)"</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error316>type_error.316</a> if a string or object key in <code>j</code> is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and <code>error_handler</code> is <code>strict</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error321>type_error.321</a> if <code>j</code> or a value nested in it is discarded; example: <code>"cannot serialize discarded value to MessagePack"</code></li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the <abbr title="JavaScript Object Notation">JSON</abbr> value <code>j</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: serialize a <abbr title="JavaScript Object Notation">JSON</abbr> value to MessagePack</summary> <p>The example shows the serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value to a byte vector in MessagePack format.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -51,4 +51,4 @@
 <span class=w>    </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=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>415</span><span class=p>]</span><span class=w> </span><span class=err>sub</span><span class=kc>t</span><span class=err>ype</span><span class=w> </span><span class=mi>300</span><span class=w> </span><span class=err>is</span><span class=w> </span><span class=kc>t</span><span class=err>oo</span><span class=w> </span><span class=err>large</span><span class=w> </span><span class=kc>f</span><span class=err>or</span><span class=w> </span><span class=kc>t</span><span class=err>he</span><span class=w> </span><span class=err>MessagePack</span><span class=w> </span><span class=err>ex</span><span class=kc>t</span><span class=w> </span><span class=kc>t</span><span class=err>ype</span><span class=w> </span><span class=err>(max</span><span class=w> </span><span class=mi>255</span><span class=err>)</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_msgpack/ >from_msgpack</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in MessagePack format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 2.0.9.</li> <li>Throws <code>out_of_range.412</code> and <code>out_of_range.415</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to serialize <code>number_integer_t</code>/<code>number_unsigned_t</code> pairs of different width correctly; before, integers could be serialized with the wrong value if <code>number_integer_t</code> was narrower than <code>number_unsigned_t</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid MessagePack.</li> </ul> <!-- 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 6, 2026 05:33:34 UTC">October 6, 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 &copy; 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.2Line truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../from_msgpack/ >from_msgpack</a> create a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input in MessagePack format</li> <li><a href=../to_cbor/ >to_cbor</a> create a <abbr title="Concise Binary Object Representation">CBOR</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bson/ >to_bson</a> create a <abbr title="Binary JSON">BSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_ubjson/ >to_ubjson</a> create a <abbr title="Universal Binary JSON">UBJSON</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bjdata/ >to_bjdata</a> create a <abbr title="Binary JData">BJData</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> <li><a href=../to_bon8/ >to_bon8</a> create a <abbr title="Binary Object Notation 8">BON8</abbr> serialization of a <abbr title="JavaScript Object Notation">JSON</abbr> value</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 2.0.9.</li> <li>Throws <code>out_of_range.412</code> and <code>out_of_range.415</code> since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Added <code>error_handler</code> parameter in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Its default, <code>keep</code>, writes the bytes of a string or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 unchanged, as before.</li> <li>Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to serialize <code>number_integer_t</code>/<code>number_unsigned_t</code> pairs of different width correctly; before, integers could be serialized with the wrong value if <code>number_integer_t</code> was narrower than <code>number_unsigned_t</code>.</li> <li>Throws <code>type_error.321</code> for a discarded value since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, a discarded value nested in an array or object was silently skipped, producing invalid MessagePack.</li> <li>Throws <code>out_of_range.407</code> for integers that do not fit 64 bits since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; previously, integers of a number type wider than 64 bits were silently truncated.</li> </ul> <!-- 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 21, 2026 08:36:31 UTC">October 21, 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 &copy; 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.comLine truncated

api/basic_json/to_msgpack/index.md

@@ -38,6 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside [-2^63, 2^64-1], which is only possible with a number type wider than 64 bits; example: `"integer number 18446744073709551616 cannot be represented by MessagePack as it does not fit [-2^63, 2^64-1]"`
 - Throws [`out_of_range.412`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range412) if the length of a string, binary value, array, or object exceeds 4294967295, the maximum MessagePack can store; example: `"MessagePack length 4294967296 exceeds maximum of 4294967295"`
 - Throws [`out_of_range.415`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range415) if the subtype of a binary value exceeds 255, the maximum of the MessagePack ext type; example: `"subtype 70000 is too large for the MessagePack ext type (max 255)"`
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string or object key in `j` is not valid UTF-8 and `error_handler` is `strict`
@@ -133,3 +134,4 @@ Output:
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before.
 - Fixed in version 3.13.0 unreleased to serialize `number_integer_t`/`number_unsigned_t` pairs of different width correctly; before, integers could be serialized with the wrong value if `number_integer_t` was narrower than `number_unsigned_t`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid MessagePack.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/macros/json_disable_unlocked_file_io.md

@@ -10,6 +10,9 @@ earlier, instead of locking the file once and reading it with the unlocked stdio
 It does not change any result: values, exceptions, and the position of the file after parsing are the same either way.
 Only the speed and the locking of the file differ (see the notes on locking below).
 
+Builds with MemorySanitizer use `std::fgetc` automatically, because the inline `getc_unlocked` of glibc reads the stdio
+buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.
+
 ## Default definition
 
 The default value is `0`: the file is locked once and read with the unlocked stdio functions where they are available.

api/macros/json_disable_unlocked_file_io/index.html

@@ -1,5 +1,5 @@
 <!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/api/macros/json_disable_unlocked_file_io/" rel="canonical"><link href=../json_disable_tuple_reference_conversion/ rel=prev><link href=../json_has_cpp_11/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>JSON_DISABLE_UNLOCKED_FILE_IO - 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=#json_disable_unlocked_file_io 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> JSON_DISABLE_UNLOCKED_FILE_IO </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 6Line truncated
-</code></pre></div> <p>When defined to <code>1</code>, parsing from a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> reads every character with <code>std::fgetc</code>, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions.</p> <p>It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).</p> <h2 id=default-definition>Default definition<a class=headerlink href=#default-definition title="Permanent link">&para;</a></h2> <p>The default value is <code>0</code>: the file is locked once and read with the unlocked stdio functions where they are available.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_UNLOCKED_FILE_IO 0</span>
+</code></pre></div> <p>When defined to <code>1</code>, parsing from a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> reads every character with <code>std::fgetc</code>, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions.</p> <p>It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).</p> <p>Builds with MemorySanitizer use <code>std::fgetc</code> automatically, because the inline <code>getc_unlocked</code> of glibc reads the stdio buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.</p> <h2 id=default-definition>Default definition<a class=headerlink href=#default-definition title="Permanent link">&para;</a></h2> <p>The default value is <code>0</code>: the file is locked once and read with the unlocked stdio functions where they are available.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_UNLOCKED_FILE_IO 0</span>
 </code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <div class="admonition note"> <p class=admonition-title>Background</p> <p>The C standard library makes every <code>std::fgetc</code> call thread-safe by locking and unlocking the <code>FILE</code> object. When parsing from a <code>FILE*</code>, the parser reads one character at a time, so this happens for every character of the input.</p> <p>Instead, the parser locks the file once when parsing starts and unlocks it when parsing ends - also when an exception is thrown - and reads the characters in between without locking:</p> <table> <thead> <tr> <th>C library</th> <th>functions</th> </tr> </thead> <tbody> <tr> <td>glibc (Linux), Apple (macOS, iOS), Android, FreeBSD, NetBSD, OpenBSD, DragonFly BSD</td> <td><code>flockfile</code>, <code>getc_unlocked</code>, <code>funlockfile</code> (POSIX)</td> </tr> <tr> <td>Microsoft (<abbr title="Microsoft Visual C++">MSVC</abbr>, clang-cl)</td> <td><code>_lock_file</code>, <code>_fgetc_nolock</code>, <code>_unlock_file</code></td> </tr> <tr> <td>others (e.g., musl, MinGW, newlib)</td> <td><code>std::fgetc</code>, as before</td> </tr> </tbody> </table> <p>This makes parsing from a <code>FILE*</code> 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with glibc, whose locking is cheaper. The binary formats (<a href=../../basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../basic_json/from_msgpack/ ><code>from_msgpack</code></a>, ...) read from a <code>FILE*</code> the same way.</p> </div> <div class="admonition note"> <p class=admonition-title>Locking</p> <p>While a value is parsed from a <code>FILE*</code>, the parsing thread holds the file's lock. The lock is recursive, so the parsing thread itself - for instance, a <a href=../../json_sax/ ><abbr title="Simple API for XML">SAX</abbr></a> handler or a <a href=../../basic_json/parser_callback_t/ >parser callback</a> - can keep using the file with stdio functions such as <code>std::ftell</code>. Other threads that use the same <code>FILE</code> object wait until the parser is done. Before, they could interleave their reads with the parser's, which made the parsed input unpredictable anyway.</p> <p>A program in which a <abbr title="Simple API for XML">SAX</abbr> handler or parser callback waits for <strong>another</strong> thread that uses the <strong>same</strong> <code>FILE</code> object would deadlock. Define the macro to <code>1</code> for such programs.</p> </div> <div class="admonition note"> <p class=admonition-title>ABI compatibility</p> <p>The value of this macro is encoded in the <a href=../../../features/namespace/ >namespace</a> (tag <code>_dufio</code>), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.</p> </div> <div class="admonition note"> <p class=admonition-title>Other inputs</p> <p>Reading from a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> is not affected by this macro; see <a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> for that input.</p> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example: parsing from a <code>FILE*</code> (default)</summary> <p>The file is locked once while it is parsed:</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;cstdio&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -23,4 +23,4 @@
 <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>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span><span class=w>  </span><span class=c1>// std::fgetc for every character</span>
 <span class=w>    </span><span class=n>std</span><span class=o>::</span><span class=n>fclose</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
 <span class=p>}</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../basic_json/parse/ ><strong>parse</strong></a> - deserialize from a compatible input</li> <li><a href=../../basic_json/sax_parse/ ><strong>sax_parse</strong></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=../json_disable_stream_bulk_scan/ ><strong>JSON_DISABLE_STREAM_BULK_SCAN</strong></a> - read a <code>std::istream</code> one character at a time</li> <li><a href=../../../features/parsing/#input-sources-and-performance>Parsing: input sources and performance</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- 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 19, 2026 20:00:58 UTC">October 19, 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 &copy; 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 38Line truncated
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../basic_json/parse/ ><strong>parse</strong></a> - deserialize from a compatible input</li> <li><a href=../../basic_json/sax_parse/ ><strong>sax_parse</strong></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=../json_disable_stream_bulk_scan/ ><strong>JSON_DISABLE_STREAM_BULK_SCAN</strong></a> - read a <code>std::istream</code> one character at a time</li> <li><a href=../../../features/parsing/#input-sources-and-performance>Parsing: input sources and performance</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- 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 21, 2026 08:22:50 UTC">October 21, 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 &copy; 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 38Line truncated

api/macros/json_disable_unlocked_file_io/index.md

@@ -8,6 +8,8 @@ When defined to `1`, parsing from a `FILE*` reads every character with `std::fge
 
 It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).
 
+Builds with MemorySanitizer use `std::fgetc` automatically, because the inline `getc_unlocked` of glibc reads the stdio buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.
+
 ## Default definition
 
 The default value is `0`: the file is locked once and read with the unlocked stdio functions where they are available.