mirror of
https://github.com/nlohmann/json.git
synced 2026-10-07 15:07:13 +00:00
deploy: e4e7d657ef
This commit is contained in:
nlohmann committed
1 parent
6cba066a3f
commit
f991906bcd
12 files changed
+70
-16
No files matched your search
@@ -50,9 +50,11 @@ The default value is `0` (disabled — existing behavior is preserved).
|
||||
```
|
||||
|
||||
Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
|
||||
element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
|
||||
affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
|
||||
`[5]`.
|
||||
element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still
|
||||
creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its
|
||||
value: an existing JSON value that happens to be a two-element array with a string as its first element, such as
|
||||
`json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own
|
||||
conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
|
||||
|
||||
!!! note "ABI compatibility"
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
</code></pre></div> <p>creates a single-element <strong>array</strong> <code>[{"key":"value"}]</code> instead of a copy of <code>obj</code>. This behavior is compiler-dependent for older compilers (<abbr title="GNU Compiler Collection">GCC</abbr> wrapped, Clang did not), but starting from Clang 20, both compilers behave the same way.</p> <p>Enabling this macro opts into copy/move semantics for this case (see <a href="https://github.com/nlohmann/json/issues/5074">#5074</a>).</p> </div> <div class="admonition warning"> <p class=admonition-title>Opt-in only</p> <p>This macro must be defined <strong>before</strong> including <code><nlohmann/json.hpp></code>. Defining it after the include has no effect.</p> </div> <div class="admonition warning"> <p class=admonition-title>Applies to every single-element list</p> <p>The macro does not only affect a single <abbr title="JavaScript Object Notation">JSON</abbr> value in braces. <strong>Any</strong> single-element braced list is treated as its element, so it no longer creates a one-element array:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j1</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{</span><span class=mi>1</span><span class=p>};</span><span class=w> </span><span class=c1>// 1, not [1]</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=n>j2</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{</span><span class=s>"text"</span><span class=p>};</span><span class=w> </span><span class=c1>// "text", not ["text"]</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=n>j3</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{{</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>}};</span><span class=w> </span><span class=c1>// [1,2], not [[1,2]]</span>
|
||||
</code></pre></div> <p>Code that relies on these producing arrays must use <code>json::array()</code> instead (see below). Lists with more than one element, and a single <code>[string, value]</code> pair such as <code>{{"key", "value"}}</code>, which still creates an object, are not affected. The library's own conversions are not affected either: for example, <code>std::tuple<int>{5}</code> still becomes <code>[5]</code>.</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>_bics</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 tip"> <p class=admonition-title>Workaround without the macro</p> <p>To explicitly create a single-element array without enabling this macro, use <code>json::array()</code>:</p> <div class=highlight><pre><span></span><code><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>array</span><span class=p>({</span><span class=n>obj</span><span class=p>});</span><span class=w> </span><span class=c1>// always creates [obj]</span>
|
||||
</code></pre></div> <p>Code that relies on these producing arrays must use <code>json::array()</code> instead (see below). Lists with more than one element, and a single <code>[string, value]</code> pair <em>written as a braced list</em>, such as <code>{{"key", "value"}}</code>, which still creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its value: an existing <abbr title="JavaScript Object Notation">JSON</abbr> value that happens to be a two-element array with a string as its first element, such as <code>json arr = {"key", 42};</code>, is still copied by <code>json j{arr};</code> rather than turned into an object. The library's own conversions are not affected either: for example, <code>std::tuple<int>{5}</code> still becomes <code>[5]</code>.</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>_bics</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 tip"> <p class=admonition-title>Workaround without the macro</p> <p>To explicitly create a single-element array without enabling this macro, use <code>json::array()</code>:</p> <div class=highlight><pre><span></span><code><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>array</span><span class=p>({</span><span class=n>obj</span><span class=p>});</span><span class=w> </span><span class=c1>// always creates [obj]</span>
|
||||
</code></pre></div> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: default behavior (macro not defined)</summary> <p>Without the macro, single-element brace initialization wraps the value in an array:</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
@@ -29,4 +29,4 @@
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=p>{</span><span class=n>obj</span><span class=p>};</span>
|
||||
<span class=w> </span><span class=c1>// j is {"key":"value"} -- copy of obj</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../home/faq/#brace-initialization-yields-arrays><abbr title="Frequently Asked Questions">FAQ</abbr>: Brace initialization yields arrays</a></li> <li><a href=../../basic_json/basic_json/ ><strong>basic_json(initializer_list_t)</strong></a> - the affected constructor</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</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> <li>Planned to become the default (with the macro removed) in version 4.0.0.</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 4, 2026 09:59:34 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../../home/faq/#brace-initialization-yields-arrays><abbr title="Frequently Asked Questions">FAQ</abbr>: Brace initialization yields arrays</a></li> <li><a href=../../basic_json/basic_json/ ><strong>basic_json(initializer_list_t)</strong></a> - the affected constructor</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</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> <li>Planned to become the default (with the macro removed) in version 4.0.0.</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 7, 2026 05:39:05 UTC">October 7, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.Line truncated
|
||||
@@ -43,7 +43,7 @@ json j2 = {"text"}; // "text", not ["text"]
|
||||
json j3 = {{1, 2}}; // [1,2], not [[1,2]]
|
||||
```
|
||||
|
||||
Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
|
||||
Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its value: an existing JSON value that happens to be a two-element array with a string as its first element, such as `json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
|
||||
|
||||
ABI compatibility
|
||||
|
||||
|
||||
@@ -8,4 +8,4 @@ make<span class=w> </span>serve<span class=w> </span>-C<span class=w> </span>doc
|
||||
make<span class=w> </span>check_mermaid<span class=w> </span>-C<span class=w> </span>docs/mkdocs<span class=w> </span><span class=c1># checks the Mermaid diagrams (requires Node.js)</span>
|
||||
</code></pre></div> <p>A new <abbr title="Application Programming Interfaces">API</abbr> page also needs an entry in <a href="https://github.com/nlohmann/json/blob/develop/docs/docset/docSet.sql"><code>docs/docset/docSet.sql</code></a>, the search index of the docset; <code>make build</code> reports missing entries.</p> <h3 id=amalgamate-the-source-code>Amalgamate the source code<a class=headerlink href=#amalgamate-the-source-code title="Permanent link">¶</a></h3> <p>The single-header files <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>single_include/nlohmann/json.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> are <strong>generated</strong> from the source files in the <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code> directory</a>. <strong>Do not</strong> edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>amalgamate
|
||||
</code></pre></div> <p>Running <code>make amalgamate</code> will also apply automatic formatting to the source files using <a href="https://astyle.sourceforge.net/"><code>Artistic Style</code></a>. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.</p> <p>If you add, rename, or remove a header in <code>include/nlohmann</code>, also regenerate the header list in <a href="https://github.com/nlohmann/json/blob/develop/BUILD.bazel"><code>BUILD.bazel</code></a> (requires CMake) by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>BUILD.bazel
|
||||
</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">¶</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">¶</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">¶</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">¶</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">¶</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">¶</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and I am not aware of approaches similar to <a href="http://re2c.org"><code>re2c</code></a> for parsing.</li> <li>Extending and updating existing <strong>bencLine truncated
|
||||
</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">¶</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">¶</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">¶</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>What is and is not covered by this guarantee is described in the <a href="https://json.nlohmann.me/community/roadmap/#api-stability">roadmap</a>.</p> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">¶</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">¶</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">¶</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and ILine truncated
|
||||
@@ -152,6 +152,8 @@ We take pride in the library being used by [numerous customers across various in
|
||||
- Changing access specifiers.
|
||||
- Changing default arguments.
|
||||
|
||||
What is and is not covered by this guarantee is described in the [roadmap](https://json.nlohmann.me/community/roadmap/#api-stability).
|
||||
|
||||
Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.
|
||||
|
||||
Breaking changes may be introduced when they are guarded with a feature macro such as [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/) which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.
|
||||
|
||||
+27
-3
@@ -25,9 +25,7 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the
|
||||
[contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api)
|
||||
for what counts as a breaking change.
|
||||
- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header
|
||||
@@ -35,6 +33,32 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not
|
||||
meant to compete with the fastest JSON libraries, see [Design goals](../home/design_goals.md).
|
||||
|
||||
## API stability
|
||||
|
||||
Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code
|
||||
that uses the public API. In particular, a 3.x release does not:
|
||||
|
||||
- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a
|
||||
member function);
|
||||
- remove or rename a function or class;
|
||||
- change which exceptions a function throws, or the [exception ids](../home/exceptions.md);
|
||||
- change access specifiers or default arguments.
|
||||
|
||||
Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are
|
||||
documented in the [release notes](../home/releases.md).
|
||||
|
||||
The following are **not** part of the public API and may change in any release, including patch releases:
|
||||
|
||||
- The text of exception messages returned by `what()`. Use the [exception id](../home/exceptions.md) to tell errors
|
||||
apart.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the
|
||||
library. The [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
|
||||
- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the
|
||||
[API reference](../api/basic_json/index.md).
|
||||
|
||||
Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see
|
||||
[Version 4.0](#version-40).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!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/community/roadmap/" rel="canonical"><link href=../governance/ rel=prev><link href=../security_policy/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Roadmap - 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=#roadmap 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> Roadmap </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-mdLine truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/community/roadmap/" rel="canonical"><link href=../governance/ rel=prev><link href=../security_policy/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Roadmap - 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=#roadmap 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> Roadmap </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-mdLine truncated
|
||||
<span class=cp>#define JSON_USE_GLOBAL_UDLS 0</span>
|
||||
<span class=cp>#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0</span>
|
||||
<span class=cp>#define JSON_BRACE_INIT_COPY_SEMANTICS 1</span>
|
||||
@@ -8,4 +8,4 @@
|
||||
<span class=cp>#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1</span>
|
||||
<span class=cp>#define JSON_DELETE_DEPRECATED_FUNCTIONS 1</span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
</code></pre></div> <p>The macros must be defined before the library header is included; setting them once in the build system is the easiest way to achieve this.</p> <h3 id=removal-of-deprecated-functions>Removal of deprecated functions<a class=headerlink href=#removal-of-deprecated-functions title="Permanent link">¶</a></h3> <p>Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your code still uses. Defining <a href=../../api/macros/json_delete_deprecated_functions/ ><code>JSON_DELETE_DEPRECATED_FUNCTIONS</code></a> to <code>1</code> turns these warnings into errors, as the deprecated functions are then deleted. The <a href=../../integration/migration_guide/#replace-deprecated-functions>migration guide</a> shows how to replace each of them.</p> <p>The <code>from_*</code> overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a call like <code>from_cbor(ptr, len)</code> would still compile: it would read <code>ptr</code> as a NUL-terminated string and convert <code>len</code> to the <code>strict</code> parameter.</p> <table> <thead> <tr> <th>Deprecated</th> <th>Since</th> <th>Migration</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=k>operator</span><span class=o><<</span><span class=p>(</span><span class=n>basic_json</span><span class=o>&</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>istream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><code class=highlight><span class=k>operator</span><span class=o>>></span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>ostream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><code>iterator_wrapper</code></td> <td>3.1.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><a href=../../api/basic_json/parse/ ><code>parse</code></a>, <a href=../../api/basic_json/accept/ ><code>accept</code></a>, and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> with an initializer list <code>{ptr, len}</code> or <code>{first, last}</code></td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a>, <a href=../../api/basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../api/basic_json/from_msgpack/ ><code>from_msgpack</code></a>, and <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> with <code>(ptr, len)</code> or an initializer list</td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/json_pointer/operator_string_t/ ><code>json_pointer::operator string_t</code></a></td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a <code>basic_json</code> type as template argument, and the overloads of <code>value</code>, <code>contains</code>, <code>operator[]</code>, and <code>at</code> accepting such a pointer</td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td>Comparing a <a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a string via <a href=../../api/json_pointer/operator_eq/ ><code>operator==</code></a> or <a href=../../api/json_pointer/operator_ne/ ><code>operator!=</code></a></td> <td>3.11.2</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bjdata/ ><code>from_bjdata</code></a> and <a href=../../api/basic_json/from_bon8/ ><code>from_bon8</code></a> with <code>(ptr, len)</code></td> <td>3.13.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> </tbody> </table> <p>The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.</p> <p>New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-fiLine truncated
|
||||
</code></pre></div> <p>The macros must be defined before the library header is included; setting them once in the build system is the easiest way to achieve this.</p> <h3 id=removal-of-deprecated-functions>Removal of deprecated functions<a class=headerlink href=#removal-of-deprecated-functions title="Permanent link">¶</a></h3> <p>Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your code still uses. Defining <a href=../../api/macros/json_delete_deprecated_functions/ ><code>JSON_DELETE_DEPRECATED_FUNCTIONS</code></a> to <code>1</code> turns these warnings into errors, as the deprecated functions are then deleted. The <a href=../../integration/migration_guide/#replace-deprecated-functions>migration guide</a> shows how to replace each of them.</p> <p>The <code>from_*</code> overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a call like <code>from_cbor(ptr, len)</code> would still compile: it would read <code>ptr</code> as a NUL-terminated string and convert <code>len</code> to the <code>strict</code> parameter.</p> <table> <thead> <tr> <th>Deprecated</th> <th>Since</th> <th>Migration</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=k>operator</span><span class=o><<</span><span class=p>(</span><span class=n>basic_json</span><span class=o>&</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>istream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><code class=highlight><span class=k>operator</span><span class=o>>></span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>ostream</span><span class=o>&</span><span class=p>)</span></code></td> <td>3.0.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><code>iterator_wrapper</code></td> <td>3.1.0</td> <td><a href=../../integration/migration_guide/#miscellaneous-functions>Miscellaneous functions</a></td> </tr> <tr> <td><a href=../../api/basic_json/parse/ ><code>parse</code></a>, <a href=../../api/basic_json/accept/ ><code>accept</code></a>, and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> with an initializer list <code>{ptr, len}</code> or <code>{first, last}</code></td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a>, <a href=../../api/basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../api/basic_json/from_msgpack/ ><code>from_msgpack</code></a>, and <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> with <code>(ptr, len)</code> or an initializer list</td> <td>3.8.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> <tr> <td><a href=../../api/json_pointer/operator_string_t/ ><code>json_pointer::operator string_t</code></a></td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a <code>basic_json</code> type as template argument, and the overloads of <code>value</code>, <code>contains</code>, <code>operator[]</code>, and <code>at</code> accepting such a pointer</td> <td>3.11.0</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td>Comparing a <a href=../../api/json_pointer/ ><code>json_pointer</code></a> with a string via <a href=../../api/json_pointer/operator_eq/ ><code>operator==</code></a> or <a href=../../api/json_pointer/operator_ne/ ><code>operator!=</code></a></td> <td>3.11.2</td> <td><a href=../../integration/migration_guide/#json-pointers><abbr title="JavaScript Object Notation">JSON</abbr> Pointers</a></td> </tr> <tr> <td><a href=../../api/basic_json/from_bjdata/ ><code>from_bjdata</code></a> and <a href=../../api/basic_json/from_bon8/ ><code>from_bon8</code></a> with <code>(ptr, len)</code></td> <td>3.13.0</td> <td><a href=../../integration/migration_guide/#parsing>Parsing</a></td> </tr> </tbody> </table> <p>The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.</p> <p>New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-fiLine truncated
|
||||
@@ -14,12 +14,31 @@ This page describes what the project intends to do, and what it does not intend
|
||||
|
||||
## What the project will not do
|
||||
|
||||
- **Break the public API of version 3.x.** See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api) for what counts as a breaking change.
|
||||
- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
|
||||
- **Require a newer C++ standard than C++11.**
|
||||
- **Break JSON conformance** or enable non-standard extensions by default.
|
||||
- **Add dependencies** or require a build step. The library remains header-only, and the single header `json.hpp` remains a complete distribution.
|
||||
- **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see [Design goals](https://json.nlohmann.me/home/design_goals/index.md).
|
||||
|
||||
## API stability
|
||||
|
||||
Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code that uses the public API. In particular, a 3.x release does not:
|
||||
|
||||
- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a member function);
|
||||
- remove or rename a function or class;
|
||||
- change which exceptions a function throws, or the [exception ids](https://json.nlohmann.me/home/exceptions/index.md);
|
||||
- change access specifiers or default arguments.
|
||||
|
||||
Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are documented in the [release notes](https://json.nlohmann.me/home/releases/index.md).
|
||||
|
||||
The following are **not** part of the public API and may change in any release, including patch releases:
|
||||
|
||||
- The text of exception messages returned by `what()`. Use the [exception id](https://json.nlohmann.me/home/exceptions/index.md) to tell errors apart.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the library. The [versioned inline namespace](https://json.nlohmann.me/features/namespace/index.md) turns mixing versions into a link error.
|
||||
- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the [API reference](https://json.nlohmann.me/api/basic_json/index.md).
|
||||
|
||||
Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see [Version 4.0](#version-40).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type conversions, are collected in issue [#3453](https://github.com/nlohmann/json/issues/3453).
|
||||
|
||||
@@ -131,6 +131,7 @@ The library maps CBOR types to JSON value types as follows:
|
||||
| Byte string | binary | 0x59 |
|
||||
| Byte string | binary | 0x5A |
|
||||
| Byte string | binary | 0x5B |
|
||||
| Byte string | binary | 0x5F |
|
||||
| UTF-8 string | string | 0x60..0x77 |
|
||||
| UTF-8 string | string | 0x78 |
|
||||
| UTF-8 string | string | 0x79 |
|
||||
@@ -156,6 +157,9 @@ The library maps CBOR types to JSON value types as follows:
|
||||
| Single-Precision Float | number_float | 0xFA |
|
||||
| Double-Precision Float | number_float | 0xFB |
|
||||
|
||||
Indefinite-length UTF-8 strings (0x7F) and byte strings (0x5F) are supported. Each chunk must be a definite-length
|
||||
string of the same major type, as required by [RFC 8949, Section 3.2.3](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.2.3).
|
||||
|
||||
!!! warning "Incomplete mapping"
|
||||
|
||||
The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mh>0xa2</span><span class=w> </span><span class=mh>0x67</span><span class=w> </span><span class=mh>0x63</span><span class=w> </span><span class=mh>0x6f</span><span class=w> </span><span class=mh>0x6d</span><span class=w> </span><span class=mh>0x70</span><span class=w> </span><span class=mh>0x61</span><span class=w> </span><span class=mh>0x63</span><span class=w> </span><span class=mh>0x74</span><span class=w> </span><span class=mh>0xf5</span><span class=w> </span><span class=mh>0x66</span><span class=w> </span><span class=mh>0x73</span><span class=w> </span><span class=mh>0x63</span><span class=w> </span><span class=mh>0x68</span><span class=w> </span><span class=mh>0x65</span><span class=w> </span><span class=mh>0x6d</span><span class=w> </span><span class=mh>0x61</span><span class=w> </span><span class=mh>0x00</span><span class=w> </span>
|
||||
</code></pre></div> </details> <h2 id=deserialization>Deserialization<a class=headerlink href=#deserialization title="Permanent link">¶</a></h2> <p>The library maps <abbr title="Concise Binary Object Representation">CBOR</abbr> types to <abbr title="JavaScript Object Notation">JSON</abbr> value types as follows:</p> <table> <thead> <tr> <th><abbr title="Concise Binary Object Representation">CBOR</abbr> type</th> <th><abbr title="JavaScript Object Notation">JSON</abbr> value type</th> <th>first byte</th> </tr> </thead> <tbody> <tr> <td>Integer</td> <td>number_unsigned</td> <td>0x00..0x17</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x18</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x19</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x1A</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x1B</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x20..0x37</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x38</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x39</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x3A</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x3B</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x40..0x57</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x58</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x59</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x5A</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x5B</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x60..0x77</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x78</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x79</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7A</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7B</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7F</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x80..0x97</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x98</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x99</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9A</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9B</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9F</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xA0..0xB7</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xB8</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xB9</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBA</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBB</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBF</td> </tr> <tr> <td>False</td> <td><code>false</code></td> <td>0xF4</td> </tr> <tr> <td>True</td> <td><code>true</code></td> <td>0xF5</td> </tr> <tr> <td>Null</td> <td><code>null</code></td> <td>0xF6</td> </tr> <tr> <td>Half-Precision Float</td> <td>number_float</td> <td>0xF9</td> </tr> <tr> <td>Single-Precision Float</td> <td>number_float</td> <td>0xFA</td> </tr> <tr> <td>Double-Precision Float</td> <td>number_float</td> <td>0xFB</td> </tr> </tbody> </table> <div class="admonition warning"> <p class=admonition-title>Incomplete mapping</p> <p>The mapping is <strong>incomplete</strong> in the sense that not all <abbr title="Concise Binary Object Representation">CBOR</abbr> types can be converted to a <abbr title="JavaScript Object Notation">JSON</abbr> value. The following <abbr title="Concise Binary Object Representation">CBOR</abbr> types are not supported and will yield parse errors:</p> <ul> <li>simple values (0xE0..0xF3, 0xF8)</li> <li>undefined (0xF7)</li> </ul> <p>Tagged items (0xC0..0xDB) are not interpreted either; see the note on tagged items below.</p> </div> <div class="admonition warning"> <p class=admonition-title>Negative integer overflow</p> <p><abbr title="Concise Binary Object Representation">CBOR</abbr> negative integers (major type 1) are decoded as <code>-1 - n</code>. If the encoded magnitude <code>n</code> is too large for the result to fit into <code>number_integer_t</code> (<code>std::int64_t</code> by default), the result is stored as <code>number_float_t</code>, like a too small integer in <abbr title="JavaScript Object Notation">JSON</abbr> text. For example, <code>-18446744073709551616</code> (<code>0x3B</code> followed by eight <code>0xFF</code> bytes) is stored as <code>-1.8446744073709552e+19</code>.</p> </div> <div class="admonition warning"> <p class=admonition-title>Object keys</p> <p><abbr title="Concise Binary Object Representation">CBOR</abbr> allows map keys of any type, whereas <abbr title="JavaScript Object Notation">JSON</abbr> only allows strings as keys in object vaLine truncated
|
||||
</code></pre></div> </details> <h2 id=deserialization>Deserialization<a class=headerlink href=#deserialization title="Permanent link">¶</a></h2> <p>The library maps <abbr title="Concise Binary Object Representation">CBOR</abbr> types to <abbr title="JavaScript Object Notation">JSON</abbr> value types as follows:</p> <table> <thead> <tr> <th><abbr title="Concise Binary Object Representation">CBOR</abbr> type</th> <th><abbr title="JavaScript Object Notation">JSON</abbr> value type</th> <th>first byte</th> </tr> </thead> <tbody> <tr> <td>Integer</td> <td>number_unsigned</td> <td>0x00..0x17</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x18</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x19</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x1A</td> </tr> <tr> <td>Unsigned integer</td> <td>number_unsigned</td> <td>0x1B</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x20..0x37</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x38</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x39</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x3A</td> </tr> <tr> <td>Negative integer</td> <td>number_integer</td> <td>0x3B</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x40..0x57</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x58</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x59</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x5A</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x5B</td> </tr> <tr> <td>Byte string</td> <td>binary</td> <td>0x5F</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x60..0x77</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x78</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x79</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7A</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7B</td> </tr> <tr> <td><abbr title="Unicode Transformation Format">UTF</abbr>-8 string</td> <td>string</td> <td>0x7F</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x80..0x97</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x98</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x99</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9A</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9B</td> </tr> <tr> <td>array</td> <td>array</td> <td>0x9F</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xA0..0xB7</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xB8</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xB9</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBA</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBB</td> </tr> <tr> <td>map</td> <td>object</td> <td>0xBF</td> </tr> <tr> <td>False</td> <td><code>false</code></td> <td>0xF4</td> </tr> <tr> <td>True</td> <td><code>true</code></td> <td>0xF5</td> </tr> <tr> <td>Null</td> <td><code>null</code></td> <td>0xF6</td> </tr> <tr> <td>Half-Precision Float</td> <td>number_float</td> <td>0xF9</td> </tr> <tr> <td>Single-Precision Float</td> <td>number_float</td> <td>0xFA</td> </tr> <tr> <td>Double-Precision Float</td> <td>number_float</td> <td>0xFB</td> </tr> </tbody> </table> <p>Indefinite-length <abbr title="Unicode Transformation Format">UTF</abbr>-8 strings (0x7F) and byte strings (0x5F) are supported. Each chunk must be a definite-length string of the same major type, as required by <a href="https://www.rfc-editor.org/rfc/rfc8949.html#section-3.2.3"><abbr title="Request for Comments">RFC</abbr> 8949, Section 3.2.3</a>.</p> <div class="admonition warning"> <p class=admonition-title>Incomplete mapping</p> <p>The mapping is <strong>incomplete</strong> in the sense that not all <abbr title="Concise Binary Object Representation">CBOR</abbr> types can be converted to a <abbr title="JavaScript Object Notation">JSON</abbr> value. The following <abbr title="Concise Binary Object Representation">CBOR</abbr> types are not supported and will yield parse errors:</p> <ul> <li>simple values (0xE0..0xF3, 0xF8)</li> <li>undefined (0xF7)</li> </ul> <p>Tagged items (0xC0..0xDB) are not interpreted either; see the note on tagged items below.</p> </div> <div class="admonition warning"> <p class=admonition-title>Negative integer overflow</p> <p><abbr title="Concise Binary Object Representation">CBOR</abbr> negative integers (major type 1) are decoded as <code>-1 - n</code>. If the encoded magnitude <code>n</code> is too large for the result to fit into <code>number_integer_t</code> (<code>std::int64_t</code> by default), the result is stored as <code>number_float_t</code>, like a too small integer in <abbr title="JavaScript Object Notation">JSON</abbr> text. For example, <code>-184Line truncated
|
||||
</code></pre></div> <p>This applies to the <a href=../../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> as well, as the key is read before it is passed on. This is a deliberate restriction of the library's <abbr title="JavaScript Object Notation">JSON</abbr> value model, not an oversight: formats built on <abbr title="Concise Binary Object Representation">CBOR</abbr> maps with integer keys, such as COSE (<a href="https://www.rfc-editor.org/rfc/rfc9052.html"><abbr title="Request for Comments">RFC</abbr> 9052</a>) or CWT (<a href="https://www.rfc-editor.org/rfc/rfc8392.html"><abbr title="Request for Comments">RFC</abbr> 8392</a>), cannot be read with this library and need a general-purpose <abbr title="Concise Binary Object Representation">CBOR</abbr> library instead.</p> </div> <div class="admonition warning"> <p class=admonition-title>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-8 in text strings</p> <p><a href="https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1"><abbr title="Request for Comments">RFC</abbr> 8949, Section 3.1</a> requires <abbr title="Concise Binary Object Representation">CBOR</abbr> text strings (major type 3) to be valid <abbr title="Unicode Transformation Format">UTF</abbr>-8, but leaves it up to the decoder whether to enforce this, so checking is opt-in: with the <a href=../../../api/basic_json/from_cbor/ ><code>error_handler</code></a> parameter left at <code>keep</code> (the default), <code>from_cbor()</code> accepts a text string (object keys included) whose bytes are not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and hands them back unchanged. Passing <code>error_handler_t::strict</code> makes <code>from_cbor()</code> check and throw <a href=../../../home/exceptions/#jsonexceptionparse_error113><code>parse_error.113</code></a> for ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-8, and <code>replace</code>/<code>ignore</code> sanitize the string instead of keeping it. However, <a href=../../../api/basic_json/dump/ ><code>dump()</code></a> still requires valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 and throws <a href=../../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> for a value read with the default <code>keep</code> handler, unless an error handler is passed that replaces or ignores the ill-formed bytes. <code>to_cbor()</code>'s own <a href=../../../api/basic_json/to_cbor/ ><code>error_handler</code></a> parameter defaults to <code>keep</code>, so such a value is written back unchanged; with <code>strict</code> (the default if <a href=../../../api/macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled), it throws the same exception instead. Byte strings (major type 2) are unaffected, since they are not required to hold text.</p> </div> <div class="admonition warning"> <p class=admonition-title>Tagged items</p> <p>Tagged items (0xC0..0xDB) will throw a parse error by default. They can be ignored by passing <code>cbor_tag_handler_t::ignore</code> to function <code>from_cbor</code>, in which case the tag is skipped and the enclosed data item is parsed on its own. Passing <code>cbor_tag_handler_t::store</code> to function <code>from_cbor</code> stores tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the innermost one is stored. Note that no tag is ever interpreted: for instance, a text string tagged with tag 0 (date/time) stays a string.</p> </div> <details class=example> <summary>Example: deserialize a <abbr title="JavaScript Object Notation">JSON</abbr> value from <abbr title="Concise Binary Object Representation">CBOR</abbr></summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
@@ -46,4 +46,4 @@
|
||||
<span class=w> </span><span class=nt>"compact"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=nt>"schema"</span><span class=p>:</span><span class=w> </span><span class=mi>0</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 4, 2026 15:53:29 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 144.Line truncated
|
||||
</code></pre></div> </details> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 7, 2026 05:38:52 UTC">October 7, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 144.Line truncated
|
||||
@@ -145,6 +145,7 @@ The library maps CBOR types to JSON value types as follows:
|
||||
| Byte string | binary | 0x59 |
|
||||
| Byte string | binary | 0x5A |
|
||||
| Byte string | binary | 0x5B |
|
||||
| Byte string | binary | 0x5F |
|
||||
| UTF-8 string | string | 0x60..0x77 |
|
||||
| UTF-8 string | string | 0x78 |
|
||||
| UTF-8 string | string | 0x79 |
|
||||
@@ -170,6 +171,8 @@ The library maps CBOR types to JSON value types as follows:
|
||||
| Single-Precision Float | number_float | 0xFA |
|
||||
| Double-Precision Float | number_float | 0xFB |
|
||||
|
||||
Indefinite-length UTF-8 strings (0x7F) and byte strings (0x5F) are supported. Each chunk must be a definite-length string of the same major type, as required by [RFC 8949, Section 3.2.3](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.2.3).
|
||||
|
||||
Incomplete mapping
|
||||
|
||||
The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
|
||||
|
||||
@@ -1 +1 @@
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // parse a JSON string\n json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n // access and modify values\n j[\"name\"] = \"Niels\";\n j[\"list\"] = {1, 0, 2};\n\n // serialize with an indent of 4 spaces\n std::cout << j.dump(4) << '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json # Homebrew\nvcpkg install nlohmann-json # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json<>;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // create a JSON object\n json j =\n {\n {\"pi\", 3.141},\n {\"happy\", true},\n {\"name\", \"Niels\"},\n {\"nothing\", nullptr},\n {\n \"answer\", {\n {\"everything\", 42}\n }\n },\n {\"list\", {1, 0, 2}},\n {\n \"object\", {\n {\"currency\", \"USD\"},\n {\"value\", 42.99}\n }\n }\n };\n\n // add new values\n j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n // count elements\n auto s = j.size();\n j[\"size\"] = s;\n\n // pretty print with indent of 4 spaces\n std::cout << std::setw(4) << j << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>{\n \"answer\": {\n \"everything\": 42\n },\n \"happy\": true,\n \"list\": [\n 1,\n 0,\n 2\n ],\n \"name\": \"Niels\",\n \"new\": {\n \"key\": {\n \"value\": [\n \"another\",\n Line truncated
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // parse a JSON string\n json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n // access and modify values\n j[\"name\"] = \"Niels\";\n j[\"list\"] = {1, 0, 2};\n\n // serialize with an indent of 4 spaces\n std::cout << j.dump(4) << '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json # Homebrew\nvcpkg install nlohmann-json # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json<>;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // create a JSON object\n json j =\n {\n {\"pi\", 3.141},\n {\"happy\", true},\n {\"name\", \"Niels\"},\n {\"nothing\", nullptr},\n {\n \"answer\", {\n {\"everything\", 42}\n }\n },\n {\"list\", {1, 0, 2}},\n {\n \"object\", {\n {\"currency\", \"USD\"},\n {\"value\", 42.99}\n }\n }\n };\n\n // add new values\n j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n // count elements\n auto s = j.size();\n j[\"size\"] = s;\n\n // pretty print with indent of 4 spaces\n std::cout << std::setw(4) << j << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>{\n \"answer\": {\n \"everything\": 42\n },\n \"happy\": true,\n \"list\": [\n 1,\n 0,\n 2\n ],\n \"name\": \"Niels\",\n \"new\": {\n \"key\": {\n \"value\": [\n \"another\",\n Line truncated
|
||||
Reference in new issue
Block a user