Compare commits
4
Commits
4e5f6962d3
...
1eb9589abb
| Author | SHA1 | Date | |
|---|---|---|---|
 nlohmann
|
1eb9589abb | ||
|
nlohmann
|
ad947e10d0 | ||
|
nlohmann
|
56189bffb2 | ||
|
nlohmann
|
207a4df1e4 |
No files matched your search
@@ -72,27 +72,11 @@
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/1"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/-"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/4"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/baz"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>endl</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// try to use an array index with leading '0'</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/01"</span><span class=n>_json_pointer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// try to use an array index that is not a number</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/one"</span><span class=n>_json_pointer</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>e</span><span class=p>.</span><span class=n>what</span><span class=p>()</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/baz"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=c1>// an array index with a leading '0' is not found</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/01"</span><span class=n>_json_pointer</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=c1>// an array index that is not a number is not found</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>contains</span><span class=p>(</span><span class=s>"/array/one"</span><span class=n>_json_pointer</span><span class=p>)</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=kc>true</span>
|
||||
<span class=kc>true</span>
|
||||
@@ -101,4 +85,6 @@
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</span>
|
||||
<span class=kc>false</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=../find/ >find</a> find a value in an object</li> <li><a href=../count/ >count</a> returns the number of occurrences of a key</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ol> <li>Added in version 3.11.0.</li> <li>Added in version 3.6.0. Extended template <code>KeyType</code> to support comparable types in version 3.11.0. Fixed in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../value/ ><code>value</code></a>, and other lookup functions.</li> <li>Added in version 3.7.0.</li> <li>Deleted overloads for integral key types 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> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> </ol> <!-- 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:46:32 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://fontaLine truncated
|
||||
@@ -160,27 +160,11 @@ int main()
|
||||
<< j.contains("/array/1"_json_pointer) << '\n'
|
||||
<< j.contains("/array/-"_json_pointer) << '\n'
|
||||
<< j.contains("/array/4"_json_pointer) << '\n'
|
||||
<< j.contains("/baz"_json_pointer) << std::endl;
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index with leading '0'
|
||||
j.contains("/array/01"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index that is not a number
|
||||
j.contains("/array/one"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
<< j.contains("/baz"_json_pointer) << '\n'
|
||||
// an array index with a leading '0' is not found
|
||||
<< j.contains("/array/01"_json_pointer) << '\n'
|
||||
// an array index that is not a number is not found
|
||||
<< j.contains("/array/one"_json_pointer) << std::endl;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -194,6 +178,8 @@ true
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// parsing input with a syntax error</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1,2,3,]"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1,2,3,]"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
|
||||
@@ -72,7 +72,7 @@ int main()
|
||||
try
|
||||
{
|
||||
// parsing input with a syntax error
|
||||
json::parse("[1,2,3,]");
|
||||
json j = json::parse("[1,2,3,]");
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
|
||||
@@ -7,8 +7,14 @@ namespace std {
|
||||
```
|
||||
|
||||
Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
|
||||
type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
|
||||
`#!cpp false`, etc.
|
||||
type of the JSON value is taken into account, so `#!json null`, `#!cpp false`, and numbers may hash differently from
|
||||
each other. Numbers that compare equal under [`operator==`](operator_eq.md) always hash equally, regardless of
|
||||
whether they are stored as signed integer, unsigned integer, or floating-point number.
|
||||
|
||||
Numbers are hashed by their value converted to `number_float_t`. Converting an integer to `number_float_t` therefore
|
||||
keeps its hash, but converting a floating-point number to an integer type is lossy and can change it: `#!cpp 0.5`
|
||||
converts to `#!cpp 0`, which need not have the same hash. Unequal numbers can also share a hash value, for example two
|
||||
large integers that convert to the same `number_float_t`.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -26,7 +32,8 @@ type of the JSON value is taken into account to have different hash values for `
|
||||
--8<-- "examples/std_hash.output"
|
||||
```
|
||||
|
||||
Note the output is platform-dependent.
|
||||
The hash values shown are examples only. They depend on the platform, the compiler, and the compiler version, and
|
||||
they can change between versions of this library. Do not persist them or rely on specific values.
|
||||
|
||||
## See also
|
||||
|
||||
@@ -36,3 +43,5 @@ type of the JSON value is taken into account to have different hash values for `
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Extended for arbitrary basic_json types in version 3.10.5.
|
||||
- Numbers that compare equal hash equally since version 3.13.0; before, `#!cpp 0`, `#!cpp 0U`, and `#!cpp 0.0` had
|
||||
different hash values.
|
||||
@@ -1,7 +1,7 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/std_hash/" rel="canonical"><link href=../std_formatter/ rel=prev><link href=../input_format_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>std::hash<basic_json> - 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=#stdhashnlohmannbasic_json 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> std::hash<basic_json> </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.5S7Line truncated
|
||||
<span class=w> </span><span class=k>struct</span><span class=w> </span><span class=nc>hash</span><span class=o><</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>basic_json</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Return a hash value for a <abbr title="JavaScript Object Notation">JSON</abbr> object. The hash function tries to rely on <code>std::hash</code> where possible. Furthermore, the type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is taken into account to have different hash values for <code class=highlight><span class=kc>null</span></code>, <code class=highlight><span class=mi>0</span></code>, <code class=highlight><span class=mi>0U</span></code>, and <code class=highlight><span class=nb>false</span></code>, etc.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example shows how to calculate hash values for different <abbr title="JavaScript Object Notation">JSON</abbr> values.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <p>Return a hash value for a <abbr title="JavaScript Object Notation">JSON</abbr> object. The hash function tries to rely on <code>std::hash</code> where possible. Furthermore, the type of the <abbr title="JavaScript Object Notation">JSON</abbr> value is taken into account, so <code class=highlight><span class=kc>null</span></code>, <code class=highlight><span class=nb>false</span></code>, and numbers may hash differently from each other. Numbers that compare equal under <a href=../operator_eq/ ><code>operator==</code></a> always hash equally, regardless of whether they are stored as signed integer, unsigned integer, or floating-point number.</p> <p>Numbers are hashed by their value converted to <code>number_float_t</code>. Converting an integer to <code>number_float_t</code> therefore keeps its hash, but converting a floating-point number to an integer type is lossy and can change it: <code class=highlight><span class=mf>0.5</span></code> converts to <code class=highlight><span class=mi>0</span></code>, which need not have the same hash. Unequal numbers can also share a hash value, for example two large integers that convert to the same <code>number_float_t</code>.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example</summary> <p>The example shows how to calculate hash values for different <abbr title="JavaScript Object Notation">JSON</abbr> values.</p> <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>
|
||||
|
||||
@@ -14,6 +14,7 @@
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash(false) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=p>(</span><span class=nb>false</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash(0) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=p>(</span><span class=mi>0</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash(0U) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=p>(</span><span class=mi>0U</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash(0.0) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=p>(</span><span class=mf>0.0</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash(</span><span class=se>\"\"</span><span class=s>) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=p>(</span><span class=s>""</span><span class=p>))</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash({}) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=o>::</span><span class=n>object</span><span class=p>())</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=s>"hash([]) = "</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>hash</span><span class=o><</span><span class=n>json</span><span class=o>></span><span class=w> </span><span class=p>{}(</span><span class=n>json</span><span class=o>::</span><span class=n>array</span><span class=p>())</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
@@ -22,10 +23,11 @@
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>hash(</span><span class=kc>null</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654435769</span>
|
||||
<span class=err>hash(</span><span class=kc>false</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436030</span>
|
||||
<span class=err>hash(</span><span class=mi>0</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436095</span>
|
||||
<span class=err>hash(</span><span class=mi>0</span><span class=err>U)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436156</span>
|
||||
<span class=err>hash(</span><span class=s2>""</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>6142509191626859748</span>
|
||||
<span class=err>hash(</span><span class=mi>0</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436221</span>
|
||||
<span class=err>hash(</span><span class=mi>0</span><span class=err>U)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436221</span>
|
||||
<span class=err>hash(</span><span class=mf>0.0</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654436221</span>
|
||||
<span class=err>hash(</span><span class=s2>""</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>11160318156688833227</span>
|
||||
<span class=err>hash(</span><span class=p>{}</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654435832</span>
|
||||
<span class=err>hash(</span><span class=p>[]</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>2654435899</span>
|
||||
<span class=err>hash(</span><span class=p>{</span><span class=nt>"hello"</span><span class=p>:</span><span class=w> </span><span class=s2>"world"</span><span class=p>}</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>4469488738203676328</span>
|
||||
</code></pre></div> <p>Note the output is platform-dependent.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../operator_eq/ >operator==</a> compares two <abbr title="JavaScript Object Notation">JSON</abbr> values for equality, consistent with equal hash values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Extended for arbitrary basic_json types in version 3.10.5.</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 2, 2026 09:32:15 UTC">October 2, 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.Line truncated
|
||||
<span class=err>hash(</span><span class=p>{</span><span class=nt>"hello"</span><span class=p>:</span><span class=w> </span><span class=s2>"world"</span><span class=p>}</span><span class=err>)</span><span class=w> </span><span class=err>=</span><span class=w> </span><span class=mi>3701319991624763853</span>
|
||||
</code></pre></div> <p>The hash values shown are examples only. They depend on the platform, the compiler, and the compiler version, and they can change between versions of this library. Do not persist them or rely on specific values.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../operator_eq/ >operator==</a> compares two <abbr title="JavaScript Object Notation">JSON</abbr> values for equality, consistent with equal hash values</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Extended for arbitrary basic_json types in version 3.10.5.</li> <li>Numbers that compare equal hash equally since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>; before, <code class=highlight><span class=mi>0</span></code>, <code class=highlight><span class=mi>0U</span></code>, and <code class=highlight><span class=mf>0.0</span></code> had different hash values.</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 17:18:51 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) CopyrighLine truncated
|
||||
@@ -6,7 +6,9 @@ namespace std {
|
||||
}
|
||||
```
|
||||
|
||||
Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the type of the JSON value is taken into account to have different hash values for `null`, `0`, `0U`, and `false`, etc.
|
||||
Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the type of the JSON value is taken into account, so `null`, `false`, and numbers may hash differently from each other. Numbers that compare equal under [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md) always hash equally, regardless of whether they are stored as signed integer, unsigned integer, or floating-point number.
|
||||
|
||||
Numbers are hashed by their value converted to `number_float_t`. Converting an integer to `number_float_t` therefore keeps its hash, but converting a floating-point number to an integer type is lossy and can change it: `0.5` converts to `0`, which need not have the same hash. Unequal numbers can also share a hash value, for example two large integers that convert to the same `number_float_t`.
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -28,6 +30,7 @@ int main()
|
||||
<< "hash(false) = " << std::hash<json> {}(json(false)) << '\n'
|
||||
<< "hash(0) = " << std::hash<json> {}(json(0)) << '\n'
|
||||
<< "hash(0U) = " << std::hash<json> {}(json(0U)) << '\n'
|
||||
<< "hash(0.0) = " << std::hash<json> {}(json(0.0)) << '\n'
|
||||
<< "hash(\"\") = " << std::hash<json> {}(json("")) << '\n'
|
||||
<< "hash({}) = " << std::hash<json> {}(json::object()) << '\n'
|
||||
<< "hash([]) = " << std::hash<json> {}(json::array()) << '\n'
|
||||
@@ -41,15 +44,16 @@ Output:
|
||||
```
|
||||
hash(null) = 2654435769
|
||||
hash(false) = 2654436030
|
||||
hash(0) = 2654436095
|
||||
hash(0U) = 2654436156
|
||||
hash("") = 6142509191626859748
|
||||
hash(0) = 2654436221
|
||||
hash(0U) = 2654436221
|
||||
hash(0.0) = 2654436221
|
||||
hash("") = 11160318156688833227
|
||||
hash({}) = 2654435832
|
||||
hash([]) = 2654435899
|
||||
hash({"hello": "world"}) = 4469488738203676328
|
||||
hash({"hello": "world"}) = 3701319991624763853
|
||||
```
|
||||
|
||||
Note the output is platform-dependent.
|
||||
The hash values shown are examples only. They depend on the platform, the compiler, and the compiler version, and they can change between versions of this library. Do not persist them or rely on specific values.
|
||||
|
||||
## See also
|
||||
|
||||
@@ -59,3 +63,4 @@ Note the output is platform-dependent.
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Extended for arbitrary basic_json types in version 3.10.5.
|
||||
- Numbers that compare equal hash equally since version 3.13.0 unreleased; before, `0`, `0U`, and `0.0` had different hash values.
|
||||
@@ -67,7 +67,7 @@ By default, implicit conversions are enabled.
|
||||
`JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
|
||||
|
||||
```cpp
|
||||
using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
|
||||
using wjson = nlohmann::json::with_string_t<std::wstring>;
|
||||
|
||||
void load(const nlohmann::json& j);
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>s</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>;</span>
|
||||
</code></pre></div> <p>When <code>JSON_USE_IMPLICIT_CONVERSIONS</code> is defined to <code>0</code>, the code above does no longer compile. Instead, it must be written like this:</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=s>"Hello, world!"</span><span class=p>;</span>
|
||||
<span class=k>auto</span><span class=w> </span><span class=n>s</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=o>></span><span class=p>();</span>
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: conversion between <code>basic_json</code> specializations</summary> <p>A <code>basic_json</code> specialization with a different string type is also no longer converted implicitly when <code>JSON_USE_IMPLICIT_CONVERSIONS</code> is defined to <code>0</code>:</p> <div class=highlight><pre><span></span><code><span class=k>using</span><span class=w> </span><span class=n>wjson</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>basic_json</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>wstring</span><span class=o>></span><span class=p>;</span>
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: conversion between <code>basic_json</code> specializations</summary> <p>A <code>basic_json</code> specialization with a different string type is also no longer converted implicitly when <code>JSON_USE_IMPLICIT_CONVERSIONS</code> is defined to <code>0</code>:</p> <div class=highlight><pre><span></span><code><span class=k>using</span><span class=w> </span><span class=n>wjson</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=o>::</span><span class=n>with_string_t</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>wstring</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>void</span><span class=w> </span><span class=nf>load</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&</span><span class=w> </span><span class=n>j</span><span class=p>);</span>
|
||||
|
||||
@@ -12,4 +12,4 @@
|
||||
<span class=n>load</span><span class=p>(</span><span class=n>wj</span><span class=p>);</span><span class=w> </span><span class=c1>// error: no implicit conversion</span>
|
||||
<span class=n>load</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>(</span><span class=n>wj</span><span class=p>));</span><span class=w> </span><span class=c1>// OK: explicit conversion</span>
|
||||
<span class=n>load</span><span class=p>(</span><span class=n>wj</span><span class=p>.</span><span class=n>get</span><span class=o><</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>></span><span class=p>());</span><span class=w> </span><span class=c1>// OK: explicit conversion</span>
|
||||
</code></pre></div> <p>Specializations that share the same string type, such as <code>json</code> and <code>ordered_json</code>, remain implicitly convertible.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../basic_json/operator_ValueType/ ><strong>operator ValueType</strong></a> - get a value (implicit)</li> <li><a href=../../basic_json/get/ ><strong>get</strong></a> - get a value (explicit)</li> <li><a href=../../../integration/cmake/#json_implicitconversions><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M11.769.066.067 23.206l12.76-10.843zm11.438 23.868L7.471 17.587 0 23.934zm.793-.198L12.298.463l1.719 19.24zM12.893 12.959l-5.025 4.298 5.62 2.248z"/></svg></span> JSON_ImplicitConversions</a> - CMake option to control the macro</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.9.0.</li> <li>Also affects the conversion between <code>basic_json</code> specializations with different string types since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </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 20:11: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 @fontawesLine truncated
|
||||
</code></pre></div> <p>Specializations that share the same string type, such as <code>json</code> and <code>ordered_json</code>, remain implicitly convertible.</p> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../basic_json/operator_ValueType/ ><strong>operator ValueType</strong></a> - get a value (implicit)</li> <li><a href=../../basic_json/get/ ><strong>get</strong></a> - get a value (explicit)</li> <li><a href=../../../integration/cmake/#json_implicitconversions><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M11.769.066.067 23.206l12.76-10.843zm11.438 23.868L7.471 17.587 0 23.934zm.793-.198L12.298.463l1.719 19.24zM12.893 12.959l-5.025 4.298 5.62 2.248z"/></svg></span> JSON_ImplicitConversions</a> - CMake option to control the macro</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.9.0.</li> <li>Also affects the conversion between <code>basic_json</code> specializations with different string types since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </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 8, 2026 14:11:16 UTC">October 8, 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 @fontawesLine truncated
|
||||
@@ -55,7 +55,7 @@ Example: conversion between `basic_json` specializations
|
||||
A `basic_json` specialization with a different string type is also no longer converted implicitly when `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
|
||||
|
||||
```
|
||||
using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
|
||||
using wjson = nlohmann::json::with_string_t<std::wstring>;
|
||||
|
||||
void load(const nlohmann::json& j);
|
||||
|
||||
|
||||
+23
-9
@@ -36,13 +36,26 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
|
||||
## 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:
|
||||
that uses the public API, unless that code opts in to a change with a macro as described [below](#version-40). 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;
|
||||
- make breaking changes to the signature of a function: the types or order of its existing parameters, its return type,
|
||||
its `noexcept` or `constexpr` specifier, or the const-ness of a member function. New parameters may be added if they
|
||||
have a default value;
|
||||
- remove or rename a function or class, or change the template parameters of a public class template;
|
||||
- change which exceptions a function throws, or the [exception ids](../home/exceptions.md);
|
||||
- change access specifiers or default arguments.
|
||||
- change access specifiers, or change or remove existing default arguments. New default arguments may be added;
|
||||
- change the JSON type that a valid input parses to, or the text that `dump()` produces for a valid value;
|
||||
- accept input that was rejected before, or reject input that was accepted before;
|
||||
- change the order in which the keys of an object are iterated. The default type sorts keys, and
|
||||
[`ordered_json`](../api/ordered_json.md) keeps insertion order;
|
||||
- change when iterators, pointers, or references are invalidated, or the state of a moved-from `basic_json`;
|
||||
- add or remove implicit conversions from `basic_json`;
|
||||
- change how `to_json` and `from_json` functions are found, or the behavior of
|
||||
[`adl_serializer`](../api/adl_serializer/index.md);
|
||||
- add pure virtual functions to the [`json_sax`](../api/json_sax/index.md) interface;
|
||||
- remove, rename, renumber, or add enumerators of `value_t`;
|
||||
- remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.
|
||||
|
||||
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).
|
||||
@@ -51,13 +64,14 @@ The following are **not** part of the public API and may change in any release,
|
||||
|
||||
- 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.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. The
|
||||
[versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
|
||||
- The hash values returned by `std::hash` for `basic_json`. Numbers that compare equal still hash equally.
|
||||
- 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).
|
||||
Breaking changes are only added behind a macro whose default keeps the 3.x behavior. See [Version 4.0](#version-40) and
|
||||
the [macro overview](../features/macros.md).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -22,22 +22,32 @@ This page describes what the project intends to do, and what it does not intend
|
||||
|
||||
## 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:
|
||||
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, unless that code opts in to a change with a macro as described [below](#version-40). 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;
|
||||
- make breaking changes to the signature of a function: the types or order of its existing parameters, its return type, its `noexcept` or `constexpr` specifier, or the const-ness of a member function. New parameters may be added if they have a default value;
|
||||
- remove or rename a function or class, or change the template parameters of a public class template;
|
||||
- change which exceptions a function throws, or the [exception ids](https://json.nlohmann.me/home/exceptions/index.md);
|
||||
- change access specifiers or default arguments.
|
||||
- change access specifiers, or change or remove existing default arguments. New default arguments may be added;
|
||||
- change the JSON type that a valid input parses to, or the text that `dump()` produces for a valid value;
|
||||
- accept input that was rejected before, or reject input that was accepted before;
|
||||
- change the order in which the keys of an object are iterated. The default type sorts keys, and [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md) keeps insertion order;
|
||||
- change when iterators, pointers, or references are invalidated, or the state of a moved-from `basic_json`;
|
||||
- add or remove implicit conversions from `basic_json`;
|
||||
- change how `to_json` and `from_json` functions are found, or the behavior of [`adl_serializer`](https://json.nlohmann.me/api/adl_serializer/index.md);
|
||||
- add pure virtual functions to the [`json_sax`](https://json.nlohmann.me/api/json_sax/index.md) interface;
|
||||
- remove, rename, renumber, or add enumerators of `value_t`;
|
||||
- remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.
|
||||
|
||||
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.
|
||||
- The ABI, including `sizeof(basic_json)` and the memory layout of its values. The [versioned inline namespace](https://json.nlohmann.me/features/namespace/index.md) turns mixing versions into a link error.
|
||||
- The hash values returned by `std::hash` for `basic_json`. Numbers that compare equal still hash equally.
|
||||
- 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).
|
||||
Breaking changes are only added behind a macro whose default keeps the 3.x behavior. See [Version 4.0](#version-40) and the [macro overview](https://json.nlohmann.me/features/macros/index.md).
|
||||
|
||||
## Version 4.0
|
||||
|
||||
|
||||
@@ -19,25 +19,9 @@ int main()
|
||||
<< j.contains("/array/1"_json_pointer) << '\n'
|
||||
<< j.contains("/array/-"_json_pointer) << '\n'
|
||||
<< j.contains("/array/4"_json_pointer) << '\n'
|
||||
<< j.contains("/baz"_json_pointer) << std::endl;
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index with leading '0'
|
||||
j.contains("/array/01"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
// try to use an array index that is not a number
|
||||
j.contains("/array/one"_json_pointer);
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
std::cout << e.what() << '\n';
|
||||
}
|
||||
<< j.contains("/baz"_json_pointer) << '\n'
|
||||
// an array index with a leading '0' is not found
|
||||
<< j.contains("/array/01"_json_pointer) << '\n'
|
||||
// an array index that is not a number is not found
|
||||
<< j.contains("/array/one"_json_pointer) << std::endl;
|
||||
}
|
||||
@@ -5,3 +5,5 @@ true
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
false
|
||||
@@ -1,11 +1,10 @@
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_array_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, custom_array_type>;
|
||||
using custom_json = nlohmann::json::with_array_t<custom_array_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -1,16 +1,10 @@
|
||||
#include <cstdint>
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_binary_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, std::vector, std::string, bool,
|
||||
std::int64_t, std::uint64_t, double, std::allocator,
|
||||
nlohmann::adl_serializer, custom_binary_type>;
|
||||
using custom_json = nlohmann::json::with_binary_t<custom_binary_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -1,12 +1,11 @@
|
||||
#include <iostream>
|
||||
#include <type_traits>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_object_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<custom_object_type, std::vector>;
|
||||
using custom_json = nlohmann::json::with_object_t<custom_object_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_string_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, std::vector, custom_string_type>;
|
||||
using custom_json = nlohmann::json::with_string_t<custom_string_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -8,7 +8,7 @@ int main()
|
||||
try
|
||||
{
|
||||
// parsing input with a syntax error
|
||||
json::parse("[1,2,3,]");
|
||||
json j = json::parse("[1,2,3,]");
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
|
||||
@@ -11,6 +11,7 @@ int main()
|
||||
<< "hash(false) = " << std::hash<json> {}(json(false)) << '\n'
|
||||
<< "hash(0) = " << std::hash<json> {}(json(0)) << '\n'
|
||||
<< "hash(0U) = " << std::hash<json> {}(json(0U)) << '\n'
|
||||
<< "hash(0.0) = " << std::hash<json> {}(json(0.0)) << '\n'
|
||||
<< "hash(\"\") = " << std::hash<json> {}(json("")) << '\n'
|
||||
<< "hash({}) = " << std::hash<json> {}(json::object()) << '\n'
|
||||
<< "hash([]) = " << std::hash<json> {}(json::array()) << '\n'
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
hash(null) = 2654435769
|
||||
hash(false) = 2654436030
|
||||
hash(0) = 2654436095
|
||||
hash(0U) = 2654436156
|
||||
hash("") = 6142509191626859748
|
||||
hash(0) = 2654436221
|
||||
hash(0U) = 2654436221
|
||||
hash(0.0) = 2654436221
|
||||
hash("") = 11160318156688833227
|
||||
hash({}) = 2654435832
|
||||
hash([]) = 2654435899
|
||||
hash({"hello": "world"}) = 4469488738203676328
|
||||
hash({"hello": "world"}) = 3701319991624763853
|
||||
@@ -64,6 +64,7 @@ serialization fails by default. The fourth argument of `dump` selects an
|
||||
- `strict` (default) — throw a [`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) exception.
|
||||
- `replace` — replace invalid bytes with the Unicode replacement character U+FFFD (`�`).
|
||||
- `ignore` — silently drop invalid bytes.
|
||||
- `keep` — copy invalid bytes to the output unchanged; the result is not valid UTF-8.
|
||||
|
||||
??? example "Example: serialize invalid UTF-8 with different error handlers"
|
||||
|
||||
|
||||
@@ -108,7 +108,7 @@
|
||||
</code></pre></div> </details> <p>The indentation character can be changed with the second argument (e.g., a tab <code class=highlight><span class=sc>'\t'</span></code>). An <code>indent</code> of <code>0</code> inserts newlines but no leading spaces, and the default of <code class=highlight><span class=mi>-1</span></code> selects the compact single-line form.</p> <h2 id=non-ascii-characters>Non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters<a class=headerlink href=#non-ascii-characters title="Permanent link">¶</a></h2> <p>Strings are stored and serialized as <abbr title="Unicode Transformation Format">UTF</abbr>-8 (see <a href=../types/#strings>types</a>). By default, <code>dump</code> copies valid non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters as-is. Setting the third argument <code>ensure_ascii</code> to <code class=highlight><span class=nb>true</span></code> escapes all non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters with <code>\uXXXX</code> sequences, so that the output contains only <abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters:</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=s>"苹果"</span><span class=p>;</span>
|
||||
<span class=n>j</span><span class=p>.</span><span class=n>dump</span><span class=p>();</span><span class=w> </span><span class=c1>// "苹果"</span>
|
||||
<span class=n>j</span><span class=p>.</span><span class=n>dump</span><span class=p>(</span><span class=mi>-1</span><span class=p>,</span><span class=w> </span><span class=sc>' '</span><span class=p>,</span><span class=w> </span><span class=nb>true</span><span class=p>);</span><span class=w> </span><span class=c1>// "苹果"</span>
|
||||
</code></pre></div> <h2 id=handling-invalid-utf-8>Handling invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8<a class=headerlink href=#handling-invalid-utf-8 title="Permanent link">¶</a></h2> <p>If a string contains invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences (for example, because it holds data in another encoding such as Latin-1), serialization fails by default. The fourth argument of <code>dump</code> selects an <a href=../../api/basic_json/error_handler_t/ ><code>error_handler</code></a>:</p> <ul> <li><code>strict</code> (default) — throw a <a href=../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> exception.</li> <li><code>replace</code> — replace invalid bytes with the Unicode replacement character U+FFFD (<code>�</code>).</li> <li><code>ignore</code> — silently drop invalid bytes.</li> </ul> <details class=example> <summary>Example: serialize invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 with different error handlers</summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
</code></pre></div> <h2 id=handling-invalid-utf-8>Handling invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8<a class=headerlink href=#handling-invalid-utf-8 title="Permanent link">¶</a></h2> <p>If a string contains invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 sequences (for example, because it holds data in another encoding such as Latin-1), serialization fails by default. The fourth argument of <code>dump</code> selects an <a href=../../api/basic_json/error_handler_t/ ><code>error_handler</code></a>:</p> <ul> <li><code>strict</code> (default) — throw a <a href=../../home/exceptions/#jsonexceptiontype_error316><code>type_error.316</code></a> exception.</li> <li><code>replace</code> — replace invalid bytes with the Unicode replacement character U+FFFD (<code>�</code>).</li> <li><code>ignore</code> — silently drop invalid bytes.</li> <li><code>keep</code> — copy invalid bytes to the output unchanged; the result is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8.</li> </ul> <details class=example> <summary>Example: serialize invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8 with different error handlers</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><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>
|
||||
@@ -140,4 +140,4 @@
|
||||
</code></pre></div> </details> <div class="admonition tip"> <p class=admonition-title>Avoiding invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8</p> <p>The best fix is to ensure that all strings are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded before storing them. See the <a href=../../home/faq/#parse-errors-reading-non-ascii-characters><abbr title="Frequently Asked Questions">FAQ</abbr> on non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters</a> for how to convert wide or Latin-1 strings.</p> </div> <h2 id=numbers-nan-and-binary-values>Numbers, <abbr title="Not a Number">NaN</abbr>, and binary values<a class=headerlink href=#numbers-nan-and-binary-values title="Permanent link">¶</a></h2> <ul> <li><strong>Numbers</strong> are serialized with enough precision to round-trip; see <a href=../types/number_handling/#number-serialization>number serialization</a>.</li> <li><strong><abbr title="Not a Number">NaN</abbr> and infinity</strong> cannot be represented in <abbr title="JavaScript Object Notation">JSON</abbr> and are serialized as <code class=highlight><span class=kc>null</span></code>; see <a href=../types/number_handling/#nan-handling><abbr title="Not a Number">NaN</abbr> handling</a>. The <a href=../binary_formats/ >binary formats</a> can preserve them.</li> <li><strong>Binary values</strong> have no <abbr title="JavaScript Object Notation">JSON</abbr> representation and are serialized as a helper object for debugging only; see <a href=../binary_values/#serialization>binary values</a>.</li> </ul> <h2 id=using-stdformat-stdprint-and-fmt>Using <code>std::format</code>, <code>std::print</code>, and <code>fmt</code><a class=headerlink href=#using-stdformat-stdprint-and-fmt title="Permanent link">¶</a></h2> <p>Since version 3.12.0, <abbr title="JavaScript Object Notation">JSON</abbr> values can be formatted directly with C++20's <a href="https://en.cppreference.com/w/cpp/utility/format/format"><code>std::format</code></a> whenever the standard library provides the <code><format></code> header (controlled by <a href=../../api/macros/json_has_std_format/ ><code>JSON_HAS_STD_FORMAT</code></a>). This is enabled by the <a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> specialization, which also makes <abbr title="JavaScript Object Notation">JSON</abbr> values work with <code>std::format_to</code> and with C++23's <code>std::print</code>/<code>std::println</code>:</p> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>print</span><span class=p>(</span><span class=s>"{}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// compact, like j.dump()</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>print</span><span class=p>(</span><span class=s>"{:2}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// pretty-printed with indent 2 (like j.dump(2))</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>println</span><span class=p>(</span><span class=s>"{:#}"</span><span class=p>,</span><span class=w> </span><span class=n>j</span><span class=p>);</span><span class=w> </span><span class=c1>// pretty-printed with the default indent</span>
|
||||
</code></pre></div> <p>The format spec mirrors the <code>dump</code> parameters: <code class=highlight><span class=s>"{:#}"</span></code> pretty-prints, a width such as <code class=highlight><span class=s>"{:2}"</span></code> sets the indent, and a fill-and-align prefix such as <code class=highlight><span class=s>"{:.>#}"</span></code> sets the indent character.</p> <p>For the <a href="https://github.com/fmtlib/fmt">{fmt}</a> library, the library ships a <a href=../../api/basic_json/format_as/ ><code>format_as</code></a> helper. Note its behavior depends on the <code>fmt</code> version; see the <a href=../../home/faq/#using-json-values-with-stdformat-or-fmt><abbr title="Frequently Asked Questions">FAQ</abbr> entry</a> for the details and a recipe for a full <code>fmt::formatter</code> specialization.</p> <h2 id=serializing-to-other-formats>Serializing to other formats<a class=headerlink href=#serializing-to-other-formats title="Permanent link">¶</a></h2> <p>Besides <abbr title="JavaScript Object Notation">JSON</abbr> text, a value can also be serialized to the more compact <a href=../binary_formats/ >binary formats</a> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>).</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../api/basic_json/dump/ ><code>dump</code></a> - serialize to a <abbr title="JavaScript Object Notation">JSON</abbr>-formatted string</li> <li><a href=../../api/operator_ltlt/ ><code>operator<<</code></a> - serialize to a stream</li> <li><a href=../../api/basic_json/to_string/ ><code>to_string</code></a> - user-defined-conversion helper</li> <li><a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with <code>std::format</code> and <code>std::print</code></li> <li><a href=../../api/basic_json/format_as/ ><code>format_as</code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with the {fmt} library</li> <li><a href=../parsing/ >Parsing</a> - the reverse operation</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 2, 2026 09:32:15 UTC">October 2, 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.Line truncated
|
||||
</code></pre></div> <p>The format spec mirrors the <code>dump</code> parameters: <code class=highlight><span class=s>"{:#}"</span></code> pretty-prints, a width such as <code class=highlight><span class=s>"{:2}"</span></code> sets the indent, and a fill-and-align prefix such as <code class=highlight><span class=s>"{:.>#}"</span></code> sets the indent character.</p> <p>For the <a href="https://github.com/fmtlib/fmt">{fmt}</a> library, the library ships a <a href=../../api/basic_json/format_as/ ><code>format_as</code></a> helper. Note its behavior depends on the <code>fmt</code> version; see the <a href=../../home/faq/#using-json-values-with-stdformat-or-fmt><abbr title="Frequently Asked Questions">FAQ</abbr> entry</a> for the details and a recipe for a full <code>fmt::formatter</code> specialization.</p> <h2 id=serializing-to-other-formats>Serializing to other formats<a class=headerlink href=#serializing-to-other-formats title="Permanent link">¶</a></h2> <p>Besides <abbr title="JavaScript Object Notation">JSON</abbr> text, a value can also be serialized to the more compact <a href=../binary_formats/ >binary formats</a> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>).</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../api/basic_json/dump/ ><code>dump</code></a> - serialize to a <abbr title="JavaScript Object Notation">JSON</abbr>-formatted string</li> <li><a href=../../api/operator_ltlt/ ><code>operator<<</code></a> - serialize to a stream</li> <li><a href=../../api/basic_json/to_string/ ><code>to_string</code></a> - user-defined-conversion helper</li> <li><a href=../../api/basic_json/std_formatter/ ><code>std::formatter<basic_json></code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with <code>std::format</code> and <code>std::print</code></li> <li><a href=../../api/basic_json/format_as/ ><code>format_as</code></a> - use <abbr title="JavaScript Object Notation">JSON</abbr> values with the {fmt} library</li> <li><a href=../parsing/ >Parsing</a> - the reverse operation</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 17:17:57 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.Line truncated
|
||||
@@ -154,6 +154,7 @@ If a string contains invalid UTF-8 sequences (for example, because it holds data
|
||||
- `strict` (default) — throw a [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) exception.
|
||||
- `replace` — replace invalid bytes with the Unicode replacement character U+FFFD (`�`).
|
||||
- `ignore` — silently drop invalid bytes.
|
||||
- `keep` — copy invalid bytes to the output unchanged; the result is not valid UTF-8.
|
||||
|
||||
Example: serialize invalid UTF-8 with different error handlers
|
||||
|
||||
|
||||
@@ -351,9 +351,8 @@ The number types can be changed with template parameters.
|
||||
|
||||
A `basic_json` type that uses `#!c long double` as floating-point type.
|
||||
|
||||
```cpp hl_lines="2"
|
||||
using json_ld = nlohmann::basic_json<std::map, std::vector, std::string, bool,
|
||||
std::int64_t, std::uint64_t, long double>;
|
||||
```cpp hl_lines="1"
|
||||
using json_ld = nlohmann::json::with_float_t<long double>;
|
||||
```
|
||||
|
||||
Note values should then be parsed with `json_ld::parse` rather than `json::parse` as the latter would parse
|
||||
|
||||
@@ -59,6 +59,5 @@ val=nan
|
||||
<span class=w> </span><span class=c1>// otherwise, take appropriate action</span>
|
||||
<span class=w> </span><span class=c1>// ...</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Note this approach also has the advantage that it can react on non-numerical <abbr title="JavaScript Object Notation">JSON</abbr> value types such as strings.</p> <p>(Example taken from <a href="https://github.com/nlohmann/json/issues/777#issuecomment-459968458">#777</a>.)</p> </div> <h3 id=determine-number-types>Determine number types<a class=headerlink href=#determine-number-types title="Permanent link">¶</a></h3> <p>As the example in <a href=#number-conversion>Number conversion</a> shows, there are different functions to determine the type of the stored number:</p> <ul> <li><a href=../../../api/basic_json/is_number/ ><code>is_number()</code></a> returns <code class=highlight><span class=nb>true</span></code> for any number type</li> <li><a href=../../../api/basic_json/is_number_integer/ ><code>is_number_integer()</code></a> returns <code class=highlight><span class=nb>true</span></code> for signed and unsigned integers</li> <li><a href=../../../api/basic_json/is_number_unsigned/ ><code>is_number_unsigned()</code></a> returns <code class=highlight><span class=nb>true</span></code> for unsigned integers only</li> <li><a href=../../../api/basic_json/is_number_float/ ><code>is_number_float()</code></a> returns <code class=highlight><span class=nb>true</span></code> for floating-point numbers</li> <li><a href=../../../api/basic_json/type_name/ ><code>type_name()</code></a> returns <code class=highlight><span class=s>"number"</span></code> for any number type</li> <li><a href=../../../api/basic_json/type/ ><code>type()</code></a> returns a different enumerator of <a href=../../../api/basic_json/value_t/ ><code>value_t</code></a> for all number types</li> </ul> <table> <thead> <tr> <th>function</th> <th>unsigned integer</th> <th>signed integer</th> <th>floating-point</th> <th>string</th> </tr> </thead> <tbody> <tr> <td><a href=../../../api/basic_json/is_number/ ><code>is_number()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_integer/ ><code>is_number_integer()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_unsigned/ ><code>is_number_unsigned()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_float/ ><code>is_number_float()</code></a></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/type_name/ ><code>type_name()</code></a></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"string"</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/type/ ><code>type()</code></a></td> <td><code>number_unsigned</code></td> <td><code>number_integer</code></td> <td><code>number_float</code></td> <td><code>string</code></td> </tr> </tbody> </table> <h3 id=template-number-types>Template number types<a class=headerlink href=#template-number-types title="Permanent link">¶</a></h3> <p>The number types can be changed with template parameters.</p> <table> <thead> <tr> <th>position</th> <th>number type</th> <th>default type</th> <th>possible values</th> </tr> </thead> <tbody> <tr> <td>5</td> <td>signed integers</td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span></code></td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int32_t</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int16_t</span></code>, etc.</td> </tr> <tr> <td>6</td> <td>unsigned integers</td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span></code></td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint32_t</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</spanLine truncated
|
||||
<span class=hll><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span><span class=p>,</span><span class=w> </span><span class=kt>long</span><span class=w> </span><span class=kt>double</span><span class=o>></span><span class=p>;</span>
|
||||
</span></code></pre></div> <p>Note values should then be parsed with <code>json_ld::parse</code> rather than <code>json::parse</code> as the latter would parse floating-point values to <code class=highlight><span class=kt>double</span></code> before then converting them to <code class=highlight><span class=kt>long</span><span class=w> </span><span class=kt>double</span></code>.</p> </div> <!-- 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 2, 2026 09:32:15 UTC">October 2, 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, Line truncated
|
||||
</code></pre></div> <p>Note this approach also has the advantage that it can react on non-numerical <abbr title="JavaScript Object Notation">JSON</abbr> value types such as strings.</p> <p>(Example taken from <a href="https://github.com/nlohmann/json/issues/777#issuecomment-459968458">#777</a>.)</p> </div> <h3 id=determine-number-types>Determine number types<a class=headerlink href=#determine-number-types title="Permanent link">¶</a></h3> <p>As the example in <a href=#number-conversion>Number conversion</a> shows, there are different functions to determine the type of the stored number:</p> <ul> <li><a href=../../../api/basic_json/is_number/ ><code>is_number()</code></a> returns <code class=highlight><span class=nb>true</span></code> for any number type</li> <li><a href=../../../api/basic_json/is_number_integer/ ><code>is_number_integer()</code></a> returns <code class=highlight><span class=nb>true</span></code> for signed and unsigned integers</li> <li><a href=../../../api/basic_json/is_number_unsigned/ ><code>is_number_unsigned()</code></a> returns <code class=highlight><span class=nb>true</span></code> for unsigned integers only</li> <li><a href=../../../api/basic_json/is_number_float/ ><code>is_number_float()</code></a> returns <code class=highlight><span class=nb>true</span></code> for floating-point numbers</li> <li><a href=../../../api/basic_json/type_name/ ><code>type_name()</code></a> returns <code class=highlight><span class=s>"number"</span></code> for any number type</li> <li><a href=../../../api/basic_json/type/ ><code>type()</code></a> returns a different enumerator of <a href=../../../api/basic_json/value_t/ ><code>value_t</code></a> for all number types</li> </ul> <table> <thead> <tr> <th>function</th> <th>unsigned integer</th> <th>signed integer</th> <th>floating-point</th> <th>string</th> </tr> </thead> <tbody> <tr> <td><a href=../../../api/basic_json/is_number/ ><code>is_number()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_integer/ ><code>is_number_integer()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_unsigned/ ><code>is_number_unsigned()</code></a></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/is_number_float/ ><code>is_number_float()</code></a></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> <td><code class=highlight><span class=nb>true</span></code></td> <td><code class=highlight><span class=nb>false</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/type_name/ ><code>type_name()</code></a></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"number"</span></code></td> <td><code class=highlight><span class=s>"string"</span></code></td> </tr> <tr> <td><a href=../../../api/basic_json/type/ ><code>type()</code></a></td> <td><code>number_unsigned</code></td> <td><code>number_integer</code></td> <td><code>number_float</code></td> <td><code>string</code></td> </tr> </tbody> </table> <h3 id=template-number-types>Template number types<a class=headerlink href=#template-number-types title="Permanent link">¶</a></h3> <p>The number types can be changed with template parameters.</p> <table> <thead> <tr> <th>position</th> <th>number type</th> <th>default type</th> <th>possible values</th> </tr> </thead> <tbody> <tr> <td>5</td> <td>signed integers</td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span></code></td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int32_t</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>int16_t</span></code>, etc.</td> </tr> <tr> <td>6</td> <td>unsigned integers</td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span></code></td> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint32_t</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</spanLine truncated
|
||||
</span></code></pre></div> <p>Note values should then be parsed with <code>json_ld::parse</code> rather than <code>json::parse</code> as the latter would parse floating-point values to <code class=highlight><span class=kt>double</span></code> before then converting them to <code class=highlight><span class=kt>long</span><span class=w> </span><span class=kt>double</span></code>.</p> </div> <!-- 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 8, 2026 14:11:16 UTC">October 8, 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, Line truncated
|
||||
@@ -288,8 +288,7 @@ Example
|
||||
A `basic_json` type that uses `long double` as floating-point type.
|
||||
|
||||
```
|
||||
using json_ld = nlohmann::basic_json<std::map, std::vector, std::string, bool,
|
||||
std::int64_t, std::uint64_t, long double>;
|
||||
using json_ld = nlohmann::json::with_float_t<long double>;
|
||||
```
|
||||
|
||||
Note values should then be parsed with `json_ld::parse` rather than `json::parse` as the latter would parse floating-point values to `double` before then converting them to `long double`.
|
||||
@@ -8,6 +8,10 @@ these requirements so they do not have to be discovered by trial and error. Each
|
||||
that are known to work for that parameter and the ones that do not, checked against Boost 1.83, Abseil 20250127.0,
|
||||
Folly, EASTL 3.21, `ankerl::unordered_dense`, `phmap`, `gtl`, `robin_hood`, `tsl::ordered_map`, and Qt 6.
|
||||
|
||||
To change a single template parameter and keep the others, use the member alias templates
|
||||
[`with_*_t`](../../api/basic_json/with_t.md); for instance, `nlohmann::json::with_float_t<long double>` is `json` with
|
||||
`#!cpp long double` as [`number_float_t`](../../api/basic_json/number_float_t.md).
|
||||
|
||||
## How to read this page
|
||||
|
||||
Requirements are split into two groups:
|
||||
@@ -143,7 +147,7 @@ struct unordered_map_object
|
||||
using base_t::base_t;
|
||||
};
|
||||
|
||||
using unordered_json = nlohmann::basic_json<unordered_map_object>;
|
||||
using unordered_json = nlohmann::json::with_object_t<unordered_map_object>;
|
||||
```
|
||||
|
||||
Whether `#!cpp std::unordered_map` can be instantiated at all depends on the standard library: `object_t` is formed
|
||||
@@ -176,7 +180,7 @@ struct flat_hash_object
|
||||
using base_t::base_t;
|
||||
};
|
||||
|
||||
using flat_hash_json = nlohmann::basic_json<flat_hash_object>;
|
||||
using flat_hash_json = nlohmann::json::with_object_t<flat_hash_object>;
|
||||
```
|
||||
|
||||
`absl::node_hash_map` keeps references to the mapped values valid across insertions; `absl::flat_hash_map` does not,
|
||||
|
||||
@@ -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/features/types/template_parameters/" rel="canonical"><link href=../number_handling/ rel=prev><link href=../../../integration/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Template Parameter Requirements - 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=#template-parameter-requirements 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> Template Parameter Requirements </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.5Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/types/template_parameters/" rel="canonical"><link href=../number_handling/ rel=prev><link href=../../../integration/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Template Parameter Requirements - 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=#template-parameter-requirements 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> Template Parameter Requirements </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.5Line truncated
|
||||
<span class=w> </span><span class=n>basic_json</span><span class=p>,</span><span class=w> </span><span class=c1>// mapped_type</span>
|
||||
<span class=w> </span><span class=n>default_object_comparator_t</span><span class=p>,</span><span class=w> </span><span class=c1>// key_compare</span>
|
||||
<span class=w> </span><span class=n>AllocatorType</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>pair</span><span class=o><</span><span class=k>const</span><span class=w> </span><span class=n>StringType</span><span class=p>,</span>
|
||||
@@ -11,7 +11,7 @@
|
||||
<span class=w> </span><span class=k>using</span><span class=w> </span><span class=n>base_t</span><span class=o>::</span><span class=n>base_t</span><span class=p>;</span>
|
||||
<span class=p>};</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>unordered_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>basic_json</span><span class=o><</span><span class=n>unordered_map_object</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>unordered_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=o>::</span><span class=n>with_object_t</span><span class=o><</span><span class=n>unordered_map_object</span><span class=o>></span><span class=p>;</span>
|
||||
</code></pre></div> <p>Whether <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>unordered_map</span></code> can be instantiated at all depends on the standard library: <code>object_t</code> is formed while <code>basic_json</code> is still incomplete (see the warning above), and libstdc++ 9 needs the size of the mapped type to instantiate the hash map's node type, so the adapter does not compile there. Newer libstdc++ versions, and the hash maps listed below, do not have that problem.</p> <p>The adapter above works verbatim for Abseil's, Boost's, <code>phmap</code>'s and <code>gtl</code>'s hash maps, which all place the hash function third and take a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>pair</span><span class=o><</span><span class=k>const</span><span class=w> </span><span class=n>Key</span><span class=p>,</span><span class=w> </span><span class=n>T</span><span class=o>></span></code> allocator fifth. Two need a different adapter:</p> <ul> <li><code>ankerl::unordered_dense</code> expects an allocator over <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>pair</span><span class=o><</span><span class=n>Key</span><span class=p>,</span><span class=w> </span><span class=n>T</span><span class=o>></span></code> (non-const key), so the allocator has to be rebound to that or dropped.</li> <li><code>robin_hood</code>'s fifth parameter is the non-type <code>MaxLoadFactor100</code>, so its adapter must drop the allocator entirely.</li> </ul> <p>None of these hash maps defines <code>key_compare</code>, so all of them additionally rely on <code>object_comparator_t</code> falling back to <a href=../../../api/basic_json/default_object_comparator_t/ ><code>default_object_comparator_t</code></a>; see <a href=../../../api/basic_json/object_comparator_t/ ><code>object_comparator_t</code></a>.</p> <h4 id=abseil-hash-maps>Abseil hash maps<a class=headerlink href=#abseil-hash-maps title="Permanent link">¶</a></h4> <p><code>absl::flat_hash_map</code> and <code>absl::node_hash_map</code> tolerate an incomplete value type, but they take a hash function as their third template argument. The same adapter as for <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>unordered_map</span></code> makes them usable:</p> <div class=highlight><pre><span></span><code><span class=k>template</span><span class=o><</span><span class=k>class</span><span class=w> </span><span class=nc>Key</span><span class=p>,</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=p>,</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>IgnoredCompare</span><span class=p>,</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>Allocator</span><span class=o>></span>
|
||||
<span class=k>struct</span><span class=w> </span><span class=nc>flat_hash_object</span>
|
||||
<span class=w> </span><span class=o>:</span><span class=w> </span><span class=n>absl</span><span class=o>::</span><span class=n>flat_hash_map</span><span class=o><</span><span class=n>Key</span><span class=p>,</span><span class=w> </span><span class=n>T</span><span class=p>,</span><span class=w> </span><span class=n>absl</span><span class=o>::</span><span class=n>Hash</span><span class=o><</span><span class=n>Key</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>equal_to</span><span class=o><</span><span class=n>Key</span><span class=o>></span><span class=p>,</span><span class=w> </span><span class=n>Allocator</span><span class=o>></span>
|
||||
@@ -20,7 +20,7 @@
|
||||
<span class=w> </span><span class=k>using</span><span class=w> </span><span class=n>base_t</span><span class=o>::</span><span class=n>base_t</span><span class=p>;</span>
|
||||
<span class=p>};</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>flat_hash_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>basic_json</span><span class=o><</span><span class=n>flat_hash_object</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>flat_hash_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=o>::</span><span class=n>with_object_t</span><span class=o><</span><span class=n>flat_hash_object</span><span class=o>></span><span class=p>;</span>
|
||||
</code></pre></div> <p><code>absl::node_hash_map</code> keeps references to the mapped values valid across insertions; <code>absl::flat_hash_map</code> does not, which makes it behave like <a href=../../../api/ordered_json/ ><code>ordered_json</code></a> with respect to <a href=../../../api/basic_json/#iterator-invalidation>iterator invalidation</a>. Both expose a <code>capacity()</code> member function, so <a href=../../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> treats them conservatively and keeps the parent pointers correct either way.</p> <h4 id=iteration-order>Iteration order<a class=headerlink href=#iteration-order title="Permanent link">¶</a></h4> <p>The library never relies on the container's iteration order for correctness; it does determine the order in which object keys are serialized by <a href=../../../api/basic_json/dump/ ><code>dump</code></a> and visited by <a href=../../../api/basic_json/items/ ><code>items</code></a>. See <a href=../../object_order/ >Object Order</a>.</p> <h4 id=capacity-marks-a-container-as-insertion-ordered><code>capacity()</code> marks a container as insertion-ordered<a class=headerlink href=#capacity-marks-a-container-as-insertion-ordered title="Permanent link">¶</a></h4> <p>With <a href=../../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> enabled, the library detects insertion-ordered maps by probing for a <code>capacity()</code> member function (<code>nlohmann::ordered_map</code> inherits it from <code>std::vector</code>) and refreshes all parent pointers after every insertion. An <code>ObjectType</code> that happens to have a <code>capacity()</code> member is therefore treated conservatively -- this is correct, but slower.</p> <h4 id=key-order-and-duplicate-keys>Key order and duplicate keys<a class=headerlink href=#key-order-and-duplicate-keys title="Permanent link">¶</a></h4> <p>The library does not sort or de-duplicate keys itself; the behavior described in <a href=../../../api/basic_json/object_t/ ><code>object_t</code></a> is entirely the behavior of the chosen container.</p> <div class="admonition tip"> <p class=admonition-title>Reference implementation</p> <p><code>docs/mkdocs/docs/examples/custom_object_type.hpp</code> wraps a private <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code> and satisfies every requirement above. It does not define <code>key_compare</code>, so <code>object_comparator_t</code> falls back to <a href=../../../api/basic_json/default_object_comparator_t/ ><code>default_object_comparator_t</code></a> -- a good starting point for a custom <code>ObjectType</code>.</p> <div class=highlight><pre><span></span><code><span class=cp>#pragma once</span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><map></span>
|
||||
@@ -167,13 +167,12 @@
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> </div> <details class=example> <summary>Example: use the custom <code>ObjectType</code></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><type_traits></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><vector></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf>"custom_object_type.hpp"</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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>basic_json</span><span class=o><</span><span class=n>custom_object_type</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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=o>::</span><span class=n>with_object_t</span><span class=o><</span><span class=n>custom_object_type</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -356,13 +355,12 @@
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> </div> <details class=example> <summary>Example: use the custom <code>ArrayType</code></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><map></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf>"custom_array_type.hpp"</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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>basic_json</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span><span class=w> </span><span class=n>custom_array_type</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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=o>::</span><span class=n>with_array_t</span><span class=o><</span><span class=n>custom_array_type</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -523,14 +521,12 @@
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> </div> <details class=example> <summary>Example: use the custom <code>StringType</code></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><map></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><vector></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf>"custom_string_type.hpp"</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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>basic_json</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span><span class=w> </span><span class=n>custom_string_type</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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=o>::</span><span class=n>with_string_t</span><span class=o><</span><span class=n>custom_string_type</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -665,19 +661,13 @@
|
||||
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>lhs</span><span class=p>.</span><span class=n>data_</span><span class=w> </span><span class=o><</span><span class=w> </span><span class=n>rhs</span><span class=p>.</span><span class=n>data_</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> </div> <details class=example> <summary>Example: use the custom <code>BinaryType</code></summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><cstdint></span>
|
||||
<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><map></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><string></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><vector></span>
|
||||
</code></pre></div> </div> <details class=example> <summary>Example: use the custom <code>BinaryType</code></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><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf>"custom_binary_type.hpp"</span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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>basic_json</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span><span class=w> </span><span class=kt>bool</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>int64_t</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>uint64_t</span><span class=p>,</span><span class=w> </span><span class=kt>double</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>allocator</span><span class=p>,</span>
|
||||
<span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>adl_serializer</span><span class=p>,</span><span class=w> </span><span class=n>custom_binary_type</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=k>using</span><span class=w> </span><span class=n>custom_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=o>::</span><span class=n>with_binary_t</span><span class=o><</span><span class=n>custom_binary_type</span><span class=o>></span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
@@ -688,4 +678,4 @@
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=kc>null</span><span class=p>}</span>
|
||||
<span class=kc>true</span>
|
||||
</code></pre></div> </details> <h3 id=compatible-containers_2>Compatible containers<a class=headerlink href=#compatible-containers_2 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Container</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code> (default)</td> <td></td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=kt>char</span><span class=o>></span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=o>></span></code></td> <td><code>dump()</code> writes the bytes as 0..255 whichever is used</td> </tr> <tr> <td><code>boost::container::vector<std::uint8_t></code>, <code>boost::container::small_vector<std::uint8_t, N></code></td> <td></td> </tr> <tr> <td><code>absl::InlinedVector<std::uint8_t, N></code></td> <td>usable here, unlike as an <code>ArrayType</code>, because the value type is complete</td> </tr> <tr> <td><code>eastl::vector<std::uint8_t></code></td> <td>usable here, unlike as an <code>ArrayType</code>, because <code>max_size()</code> is not needed</td> </tr> <tr> <td><code>folly::fbvector<std::uint8_t></code></td> <td>requires C++20, see the note above</td> </tr> </tbody> </table> <h3 id=containers-that-cannot-be-used_2>Containers that cannot be used<a class=headerlink href=#containers-that-cannot-be-used_2 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Container</th> <th>Reason</th> </tr> </thead> <tbody> <tr> <td><code>QByteArray</code></td> <td>no <code>empty()</code> (it spells that <code>isEmpty()</code>); its <code>insert</code> takes an index rather than an iterator; and it converts to <code>string_t</code>, which makes <code>to_json</code> ambiguous between a string and a binary value</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code></td> <td><code>binary_t::container_type</code> and <code>string_t</code> would be the same type, so the two <a href=../../../api/basic_json/swap/ ><code>swap</code></a> overloads collide and <code>basic_json</code> cannot be instantiated at all</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code></td> <td>storage is not contiguous, so there is no <code>data()</code></td> </tr> <tr> <td>containers whose <code>value_type</code> is wider than one byte</td> <td>see above -- accepted by the compiler, wrong at runtime</td> </tr> </tbody> </table> <h2 id=custombaseclass><code>CustomBaseClass</code><a class=headerlink href=#custombaseclass title="Permanent link">¶</a></h2> <p><code>CustomBaseClass</code> is an extension point: unless it is <code class=highlight><span class=kt>void</span></code> (the default, which selects the empty <code>nlohmann::json_default_base</code>), <code>basic_json</code> publicly derives from it.</p> <h3 id=always-required_9>Always required<a class=headerlink href=#always-required_9 title="Permanent link">¶</a></h3> <ul> <li>A non-<code>final</code>, default-constructible class type.</li> <li><code>basic_json</code> is copy-/move-constructible and copy-/move-assignable only if <code>CustomBaseClass</code> is.</li> </ul> <h3 id=notes_2>Notes<a class=headerlink href=#notes_2 title="Permanent link">¶</a></h3> <p><code>basic_json</code> is documented to be a <a href="https://en.cppreference.com/w/cpp/named_req/StandardLayoutType">StandardLayoutType</a>. Because <code>basic_json</code> has non-static data members of its own, a <code>CustomBaseClass</code> with non-static data members forfeits this guarantee.</p> <p>Note the namespace of <code>CustomBaseClass</code> becomes an associated namespace of <code>basic_json</code> for the purpose of argument-dependent lookup.</p> <p>See <a href=../../../api/basic_json/json_base_class_t/ ><code>json_base_class_t</code></a> for an example.</p> <h3 id=compatible-types_6>Compatible types<a class=headerlink href=#compatible-types_6 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Type</th> <th>Support</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=kt>void</span></code> (default)</td> <td>an empty base class is used; no effect on <code>basic_json</code></td> </tr> <tr> <td>any default-constructible, non-<code>final</code> class</td> <td>full; see <a href=../../../api/basic_json/json_base_class_t/ ><code>json_base_class_t</code></a></td> </tr>Line truncated
|
||||
</code></pre></div> </details> <h3 id=compatible-containers_2>Compatible containers<a class=headerlink href=#compatible-containers_2 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Container</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code> (default)</td> <td></td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=kt>char</span><span class=o>></span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>byte</span><span class=o>></span></code></td> <td><code>dump()</code> writes the bytes as 0..255 whichever is used</td> </tr> <tr> <td><code>boost::container::vector<std::uint8_t></code>, <code>boost::container::small_vector<std::uint8_t, N></code></td> <td></td> </tr> <tr> <td><code>absl::InlinedVector<std::uint8_t, N></code></td> <td>usable here, unlike as an <code>ArrayType</code>, because the value type is complete</td> </tr> <tr> <td><code>eastl::vector<std::uint8_t></code></td> <td>usable here, unlike as an <code>ArrayType</code>, because <code>max_size()</code> is not needed</td> </tr> <tr> <td><code>folly::fbvector<std::uint8_t></code></td> <td>requires C++20, see the note above</td> </tr> </tbody> </table> <h3 id=containers-that-cannot-be-used_2>Containers that cannot be used<a class=headerlink href=#containers-that-cannot-be-used_2 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Container</th> <th>Reason</th> </tr> </thead> <tbody> <tr> <td><code>QByteArray</code></td> <td>no <code>empty()</code> (it spells that <code>isEmpty()</code>); its <code>insert</code> takes an index rather than an iterator; and it converts to <code>string_t</code>, which makes <code>to_json</code> ambiguous between a string and a binary value</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code></td> <td><code>binary_t::container_type</code> and <code>string_t</code> would be the same type, so the two <a href=../../../api/basic_json/swap/ ><code>swap</code></a> overloads collide and <code>basic_json</code> cannot be instantiated at all</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>deque</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>></span></code></td> <td>storage is not contiguous, so there is no <code>data()</code></td> </tr> <tr> <td>containers whose <code>value_type</code> is wider than one byte</td> <td>see above -- accepted by the compiler, wrong at runtime</td> </tr> </tbody> </table> <h2 id=custombaseclass><code>CustomBaseClass</code><a class=headerlink href=#custombaseclass title="Permanent link">¶</a></h2> <p><code>CustomBaseClass</code> is an extension point: unless it is <code class=highlight><span class=kt>void</span></code> (the default, which selects the empty <code>nlohmann::json_default_base</code>), <code>basic_json</code> publicly derives from it.</p> <h3 id=always-required_9>Always required<a class=headerlink href=#always-required_9 title="Permanent link">¶</a></h3> <ul> <li>A non-<code>final</code>, default-constructible class type.</li> <li><code>basic_json</code> is copy-/move-constructible and copy-/move-assignable only if <code>CustomBaseClass</code> is.</li> </ul> <h3 id=notes_2>Notes<a class=headerlink href=#notes_2 title="Permanent link">¶</a></h3> <p><code>basic_json</code> is documented to be a <a href="https://en.cppreference.com/w/cpp/named_req/StandardLayoutType">StandardLayoutType</a>. Because <code>basic_json</code> has non-static data members of its own, a <code>CustomBaseClass</code> with non-static data members forfeits this guarantee.</p> <p>Note the namespace of <code>CustomBaseClass</code> becomes an associated namespace of <code>basic_json</code> for the purpose of argument-dependent lookup.</p> <p>See <a href=../../../api/basic_json/json_base_class_t/ ><code>json_base_class_t</code></a> for an example.</p> <h3 id=compatible-types_6>Compatible types<a class=headerlink href=#compatible-types_6 title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Type</th> <th>Support</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=kt>void</span></code> (default)</td> <td>an empty base class is used; no effect on <code>basic_json</code></td> </tr> <tr> <td>any default-constructible, non-<code>final</code> class</td> <td>full; see <a href=../../../api/basic_json/json_base_class_t/ ><code>json_base_class_t</code></a></td> </tr>Line truncated
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
Class [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) is configurable through eleven template parameters. The library never formally states what a type passed for one of these parameters has to provide -- the requirements are implied by the way the library uses the resulting [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md), [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md), [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md), etc. This page collects these requirements so they do not have to be discovered by trial and error. Each section lists the concrete types that are known to work for that parameter and the ones that do not, checked against Boost 1.83, Abseil 20250127.0, Folly, EASTL 3.21, `ankerl::unordered_dense`, `phmap`, `gtl`, `robin_hood`, `tsl::ordered_map`, and Qt 6.
|
||||
|
||||
To change a single template parameter and keep the others, use the member alias templates [`with_*_t`](https://json.nlohmann.me/api/basic_json/with_t/index.md); for instance, `nlohmann::json::with_float_t<long double>` is `json` with `long double` as [`number_float_t`](https://json.nlohmann.me/api/basic_json/number_float_t/index.md).
|
||||
|
||||
## How to read this page
|
||||
|
||||
Requirements are split into two groups:
|
||||
@@ -94,7 +96,7 @@ struct unordered_map_object
|
||||
using base_t::base_t;
|
||||
};
|
||||
|
||||
using unordered_json = nlohmann::basic_json<unordered_map_object>;
|
||||
using unordered_json = nlohmann::json::with_object_t<unordered_map_object>;
|
||||
```
|
||||
|
||||
Whether `std::unordered_map` can be instantiated at all depends on the standard library: `object_t` is formed while `basic_json` is still incomplete (see the warning above), and libstdc++ 9 needs the size of the mapped type to instantiate the hash map's node type, so the adapter does not compile there. Newer libstdc++ versions, and the hash maps listed below, do not have that problem.
|
||||
@@ -119,7 +121,7 @@ struct flat_hash_object
|
||||
using base_t::base_t;
|
||||
};
|
||||
|
||||
using flat_hash_json = nlohmann::basic_json<flat_hash_object>;
|
||||
using flat_hash_json = nlohmann::json::with_object_t<flat_hash_object>;
|
||||
```
|
||||
|
||||
`absl::node_hash_map` keeps references to the mapped values valid across insertions; `absl::flat_hash_map` does not, which makes it behave like [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md) with respect to [iterator invalidation](https://json.nlohmann.me/api/basic_json/#iterator-invalidation). Both expose a `capacity()` member function, so [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) treats them conservatively and keeps the parent pointers correct either way.
|
||||
@@ -292,13 +294,12 @@ Example: use the custom `ObjectType`
|
||||
```
|
||||
#include <iostream>
|
||||
#include <type_traits>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_object_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<custom_object_type, std::vector>;
|
||||
using custom_json = nlohmann::json::with_object_t<custom_object_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -553,13 +554,12 @@ Example: use the custom `ArrayType`
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_array_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, custom_array_type>;
|
||||
using custom_json = nlohmann::json::with_array_t<custom_array_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -828,14 +828,12 @@ Example: use the custom `StringType`
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_string_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, std::vector, custom_string_type>;
|
||||
using custom_json = nlohmann::json::with_string_t<custom_string_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -1128,19 +1126,13 @@ class custom_binary_type
|
||||
Example: use the custom `BinaryType`
|
||||
|
||||
```
|
||||
#include <cstdint>
|
||||
#include <iostream>
|
||||
#include <map>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
#include "custom_binary_type.hpp"
|
||||
|
||||
using custom_json = nlohmann::basic_json<std::map, std::vector, std::string, bool,
|
||||
std::int64_t, std::uint64_t, double, std::allocator,
|
||||
nlohmann::adl_serializer, custom_binary_type>;
|
||||
using custom_json = nlohmann::json::with_binary_t<custom_binary_type>;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -771,6 +771,7 @@ as well for a string value or object key that is not valid UTF-8 if their `error
|
||||
- Pass an error handler as last parameter to the `dump()` function to avoid this exception:
|
||||
- `json::error_handler_t::replace` will replace invalid bytes sequences with `U+FFFD`
|
||||
- `json::error_handler_t::ignore` will silently ignore invalid byte sequences
|
||||
- `json::error_handler_t::keep` will copy invalid byte sequences to the output unchanged
|
||||
|
||||
### json.exception.type_error.317
|
||||
|
||||
|
||||
@@ -88,7 +88,7 @@
|
||||
<span class=w> </span><span class=k>try</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
<span class=w> </span><span class=c1>// parsing input with a syntax error</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1,2,3,]"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1,2,3,]"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=p>}</span>
|
||||
<span class=w> </span><span class=k>catch</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_error</span><span class=o>&</span><span class=w> </span><span class=n>e</span><span class=p>)</span>
|
||||
<span class=w> </span><span class=p>{</span>
|
||||
@@ -220,7 +220,7 @@ exception id: 308
|
||||
</code></pre></div> </div> <h3 id=jsonexceptiontype_error314>json.exception.type_error.314<a class=headerlink href=#jsonexceptiontype_error314 title="Permanent link">¶</a></h3> <p>The <a href=../../api/basic_json/unflatten/ ><code>unflatten()</code></a> function only works for an object whose keys are <abbr title="JavaScript Object Notation">JSON</abbr> Pointers.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Calling <code>unflatten()</code> on an array <code class=highlight><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>]</span></code>:</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.314] only objects can be unflattened
|
||||
</code></pre></div> </div> <h3 id=jsonexceptiontype_error315>json.exception.type_error.315<a class=headerlink href=#jsonexceptiontype_error315 title="Permanent link">¶</a></h3> <p>The <a href=../../api/basic_json/unflatten/ ><code>unflatten()</code></a> function only works for an object whose keys are <abbr title="JavaScript Object Notation">JSON</abbr> Pointers and whose values are primitive.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Calling <code>unflatten()</code> on an object <code class=highlight><span class=p>{</span><span class=s2>"/1"</span><span class=p>,</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>]}</span></code>:</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.315] values in object must be primitive
|
||||
</code></pre></div> </div> <h3 id=jsonexceptiontype_error316>json.exception.type_error.316<a class=headerlink href=#jsonexceptiontype_error316 title="Permanent link">¶</a></h3> <p>The <a href=../../api/basic_json/dump/ ><code>dump()</code></a> function only works with <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded strings; that is, if you assign a <code>std::string</code> to a <abbr title="JavaScript Object Notation">JSON</abbr> value, make sure it is <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. See the <abbr title="Frequently Asked Questions">FAQ</abbr> entry on <a href=../faq/#serializing-untrusted-or-invalid-utf-8>serializing untrusted or invalid <abbr title="Unicode Transformation Format">UTF</abbr>-8</a> for background and the recommended fix.</p> <p>The binary writers <a href=../../api/basic_json/to_cbor/ ><code>to_cbor()</code></a>, <a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson()</code></a>, <a href=../../api/basic_json/to_bjdata/ ><code>to_bjdata()</code></a>, and <a href=../../api/basic_json/to_bson/ ><code>to_bson()</code></a> throw this exception as well for a string value or object key that is not valid <abbr title="Unicode Transformation Format">UTF</abbr>-8 if their <code>error_handler</code> is <code>strict</code> (the default if <a href=../../api/macros/json_strict_binary_utf8/ ><code>JSON_STRICT_BINARY_UTF8</code></a> is enabled). So does <a href=../../api/basic_json/to_msgpack/ ><code>to_msgpack()</code></a> if <code>error_handler_t::strict</code> is passed.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Calling <code>dump()</code> on a <abbr title="JavaScript Object Notation">JSON</abbr> value containing an <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 encoded string: <div class=highlight><pre><span></span><code>[json.exception.type_error.316] invalid UTF-8 byte at index 15: 0x6F
|
||||
</code></pre></div></p> </div> <div class="admonition tip"> <p class=admonition-title>Tip</p> <ul> <li>Store the source file with <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoding.</li> <li>Pass an error handler as last parameter to the <code>dump()</code> function to avoid this exception:<ul> <li><code>json::error_handler_t::replace</code> will replace invalid bytes sequences with <code>U+FFFD</code> </li> <li><code>json::error_handler_t::ignore</code> will silently ignore invalid byte sequences</li> </ul> </li> </ul> </div> <h3 id=jsonexceptiontype_error317>json.exception.type_error.317<a class=headerlink href=#jsonexceptiontype_error317 title="Permanent link">¶</a></h3> <p>The dynamic type of the object cannot be represented in the requested serialization format (e.g., a raw <code>true</code> or <code>null</code> <abbr title="JavaScript Object Notation">JSON</abbr> object cannot be serialized to <abbr title="Binary JSON">BSON</abbr>)</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p>Serializing <code class=highlight><span class=kc>null</span></code> to <abbr title="Binary JSON">BSON</abbr>: <div class=highlight><pre><span></span><code>[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is null
|
||||
</code></pre></div></p> </div> <div class="admonition tip"> <p class=admonition-title>Tip</p> <ul> <li>Store the source file with <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoding.</li> <li>Pass an error handler as last parameter to the <code>dump()</code> function to avoid this exception:<ul> <li><code>json::error_handler_t::replace</code> will replace invalid bytes sequences with <code>U+FFFD</code> </li> <li><code>json::error_handler_t::ignore</code> will silently ignore invalid byte sequences</li> <li><code>json::error_handler_t::keep</code> will copy invalid byte sequences to the output unchanged</li> </ul> </li> </ul> </div> <h3 id=jsonexceptiontype_error317>json.exception.type_error.317<a class=headerlink href=#jsonexceptiontype_error317 title="Permanent link">¶</a></h3> <p>The dynamic type of the object cannot be represented in the requested serialization format (e.g., a raw <code>true</code> or <code>null</code> <abbr title="JavaScript Object Notation">JSON</abbr> object cannot be serialized to <abbr title="Binary JSON">BSON</abbr>)</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p>Serializing <code class=highlight><span class=kc>null</span></code> to <abbr title="Binary JSON">BSON</abbr>: <div class=highlight><pre><span></span><code>[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is null
|
||||
</code></pre></div> Serializing <code class=highlight><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>]</span></code> to <abbr title="Binary JSON">BSON</abbr>: <div class=highlight><pre><span></span><code>[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is array
|
||||
</code></pre></div></p> </div> <div class="admonition tip"> <p class=admonition-title>Tip</p> <p>Encapsulate the <abbr title="JavaScript Object Notation">JSON</abbr> value in an object. That is, instead of serializing <code class=highlight><span class=kc>true</span></code>, serialize <code class=highlight><span class=p>{</span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>}</span></code></p> </div> <h3 id=jsonexceptiontype_error318>json.exception.type_error.318<a class=headerlink href=#jsonexceptiontype_error318 title="Permanent link">¶</a></h3> <p>With <a href=../../api/macros/json_use_objects_for_enum_keyed_maps/ ><code>JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS</code></a>, a map with enum keys is stored as an object. This exception is thrown if two of its keys are converted to the same string, so one of the entries would be lost. This happens, for instance, if <a href=../../api/macros/nlohmann_json_serialize_enum/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM</code></a> does not list an enumerator and it is therefore converted like the first listed one.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.318] duplicate object key 'red'
|
||||
</code></pre></div> </div> <h3 id=jsonexceptiontype_error321>json.exception.type_error.321<a class=headerlink href=#jsonexceptiontype_error321 title="Permanent link">¶</a></h3> <p>A discarded value (one created by <a href=../../api/basic_json/parse/ ><code>parse()</code></a> with a callback that returns <code>false</code> for the value, or by default-constructing a <a href=../../api/basic_json/ ><code>basic_json</code></a> with <a href=../../api/basic_json/value_t/ ><code>value_t::discarded</code></a>) was passed to a binary serialization function, either directly or nested in an array or object. There is no way to represent a discarded value in <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>, <abbr title="Binary JData">BJData</abbr>, or <abbr title="Binary JSON">BSON</abbr>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Serializing <code class=highlight><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></code> to <abbr title="Concise Binary Object Representation">CBOR</abbr>, where the second element was discarded by a parser callback: <div class=highlight><pre><span></span><code>[json.exception.type_error.321] cannot serialize discarded value to CBOR
|
||||
@@ -300,4 +300,4 @@ array index 18446744073709551616 exceeds size_type
|
||||
exception id: 501
|
||||
</code></pre></div> </details> <h3 id=jsonexceptionother_error501>json.exception.other_error.501<a class=headerlink href=#jsonexceptionother_error501 title="Permanent link">¶</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch operation 'test' failed. The unsuccessful operation is also printed.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Executing <code class=highlight><span class=p>{</span><span class=nt>"op"</span><span class=p>:</span><span class=s2>"test"</span><span class=p>,</span><span class=w> </span><span class=nt>"path"</span><span class=p>:</span><span class=s2>"/baz"</span><span class=p>,</span><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=s2>"bar"</span><span class=p>}</span></code> on <code class=highlight><span class=p>{</span><span class=nt>"baz"</span><span class=p>:</span><span class=w> </span><span class=s2>"qux"</span><span class=p>}</span></code>:</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
|
||||
</code></pre></div> </div> <h3 id=jsonexceptionother_error502>json.exception.other_error.502<a class=headerlink href=#jsonexceptionother_error502 title="Permanent link">¶</a></h3> <p><a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson</code></a> and <a href=../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a> were called with <code>use_type = true</code> but <code>use_size = false</code>. <abbr title="Universal Binary JSON">UBJSON</abbr> requires a size marker (<code>#</code>) after a type marker (<code>$</code>).</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.502] use_type requires use_size = true
|
||||
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was 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>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 6, 2026 05:33:34 UTC">October 6, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 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.coLine truncated
|
||||
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was 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>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <!-- 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 17:17:57 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.coLine truncated
|
||||
@@ -168,7 +168,7 @@ int main()
|
||||
try
|
||||
{
|
||||
// parsing input with a syntax error
|
||||
json::parse("[1,2,3,]");
|
||||
json j = json::parse("[1,2,3,]");
|
||||
}
|
||||
catch (const json::parse_error& e)
|
||||
{
|
||||
@@ -876,6 +876,7 @@ Tip
|
||||
- Pass an error handler as last parameter to the `dump()` function to avoid this exception:
|
||||
- `json::error_handler_t::replace` will replace invalid bytes sequences with `U+FFFD`
|
||||
- `json::error_handler_t::ignore` will silently ignore invalid byte sequences
|
||||
- `json::error_handler_t::keep` will copy invalid byte sequences to the output unchanged
|
||||
|
||||
### json.exception.type_error.317
|
||||
|
||||
|
||||
+1
-1
@@ -85,7 +85,7 @@ The library supports **Unicode input** as follows:
|
||||
- The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
|
||||
- Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
|
||||
- The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
|
||||
- When you store strings with different encodings in the library, calling [`dump()`](../api/basic_json/dump.md) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
|
||||
- When you store strings with different encodings in the library, calling [`dump()`](../api/basic_json/dump.md) may throw an exception unless `json::error_handler_t::replace`, `json::error_handler_t::ignore`, or `json::error_handler_t::keep` are used as error handlers.
|
||||
|
||||
In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or ISO 8859-1 is often the standard encoding.
|
||||
|
||||
|
||||
+2
-2
@@ -8,7 +8,7 @@
|
||||
|
||||
<span class=n>json</span><span class=w> </span><span class=n>obj</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{{</span><span class=s>"key"</span><span class=p>,</span><span class=w> </span><span class=s>"value"</span><span class=p>}};</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>// -> {"key":"value"} (copy, not array)</span>
|
||||
</code></pre></div> <p>Without the macro (default behavior), <code>json j{obj}</code> creates <code>[{"key":"value"}]</code>. This opt-in macro fixes issue #5074 while preserving backwards compatibility for existing code.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">¶</a></h2> <h3 id=relaxed-parsing>Relaxed parsing<a class=headerlink href=#relaxed-parsing title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Can you add an option to ignore trailing commas?</p> </div> <p>This library does not support any feature that would jeopardize interoperability.</p> <h3 id=parse-errors-reading-non-ascii-characters>Parse errors reading non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters<a class=headerlink href=#parse-errors-reading-non-ascii-characters title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why is the parser complaining about a Chinese character?</li> <li>Does the library support Unicode?</li> <li>I get an exception <code>[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"</code></li> </ul> </div> <p>The library supports <strong>Unicode input</strong> as follows:</p> <ul> <li>Only <strong><abbr title="Unicode Transformation Format">UTF</abbr>-8</strong> encoded input is supported, which is the default encoding for <abbr title="JavaScript Object Notation">JSON</abbr>, according to <a href="https://tools.ietf.org/html/rfc8259.html#section-8.1"><abbr title="Request for Comments">RFC</abbr> 8259</a>.</li> <li><code>std::u16string</code> and <code>std::u32string</code> can be parsed, assuming <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.</li> <li>Other encodings such as Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 are <strong>not</strong> supported and will yield parse or serialization errors.</li> <li>The library will not replace <a href="http://www.unicode.org/faq/private_use.html#nonchar1">Unicode noncharacters</a>.</li> <li>Invalid surrogates (e.g., incomplete pairs such as <code>\uDEAD</code>) will yield parse errors.</li> <li>The strings stored in the library are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. When using the default string type (<code>std::string</code>), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.</li> <li>When you store strings with different encodings in the library, calling <a href=../../api/basic_json/dump/ ><code>dump()</code></a> may throw an exception unless <code>json::error_handler_t::replace</code> or <code>json::error_handler_t::ignore</code> are used as error handlers.</li> </ul> <p>In most cases, the parser is right to complain, because the input is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 is often the standard encoding.</p> <h3 id=nul-bytes-in-the-input>NUL bytes in the input<a class=headerlink href=#nul-bytes-in-the-input title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why does <a href=../../api/basic_json/parse/ ><code>json::parse()</code></a> silently ignore part of my input?</li> <li>Why does a <code>std::string</code>/buffer with extra data after the <abbr title="JavaScript Object Notation">JSON</abbr> text parse without error, while a similar-looking string with extra text does not?</li> </ul> </div> <p>A <code>'\0'</code> (NUL) byte anywhere in the input is treated the same as the real end of the input, rather than as an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored, without a parse error — including further, otherwise well-formed <abbr title="JavaScript Object Notation">JSON</abbr>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=p>);</span><span class=w> </span><span class=c1>// == 123, no error</span>
|
||||
</code></pre></div> <p>Without the macro (default behavior), <code>json j{obj}</code> creates <code>[{"key":"value"}]</code>. This opt-in macro fixes issue #5074 while preserving backwards compatibility for existing code.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">¶</a></h2> <h3 id=relaxed-parsing>Relaxed parsing<a class=headerlink href=#relaxed-parsing title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Can you add an option to ignore trailing commas?</p> </div> <p>This library does not support any feature that would jeopardize interoperability.</p> <h3 id=parse-errors-reading-non-ascii-characters>Parse errors reading non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters<a class=headerlink href=#parse-errors-reading-non-ascii-characters title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why is the parser complaining about a Chinese character?</li> <li>Does the library support Unicode?</li> <li>I get an exception <code>[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"</code></li> </ul> </div> <p>The library supports <strong>Unicode input</strong> as follows:</p> <ul> <li>Only <strong><abbr title="Unicode Transformation Format">UTF</abbr>-8</strong> encoded input is supported, which is the default encoding for <abbr title="JavaScript Object Notation">JSON</abbr>, according to <a href="https://tools.ietf.org/html/rfc8259.html#section-8.1"><abbr title="Request for Comments">RFC</abbr> 8259</a>.</li> <li><code>std::u16string</code> and <code>std::u32string</code> can be parsed, assuming <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.</li> <li>Other encodings such as Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 are <strong>not</strong> supported and will yield parse or serialization errors.</li> <li>The library will not replace <a href="http://www.unicode.org/faq/private_use.html#nonchar1">Unicode noncharacters</a>.</li> <li>Invalid surrogates (e.g., incomplete pairs such as <code>\uDEAD</code>) will yield parse errors.</li> <li>The strings stored in the library are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. When using the default string type (<code>std::string</code>), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.</li> <li>When you store strings with different encodings in the library, calling <a href=../../api/basic_json/dump/ ><code>dump()</code></a> may throw an exception unless <code>json::error_handler_t::replace</code>, <code>json::error_handler_t::ignore</code>, or <code>json::error_handler_t::keep</code> are used as error handlers.</li> </ul> <p>In most cases, the parser is right to complain, because the input is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 is often the standard encoding.</p> <h3 id=nul-bytes-in-the-input>NUL bytes in the input<a class=headerlink href=#nul-bytes-in-the-input title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why does <a href=../../api/basic_json/parse/ ><code>json::parse()</code></a> silently ignore part of my input?</li> <li>Why does a <code>std::string</code>/buffer with extra data after the <abbr title="JavaScript Object Notation">JSON</abbr> text parse without error, while a similar-looking string with extra text does not?</li> </ul> </div> <p>A <code>'\0'</code> (NUL) byte anywhere in the input is treated the same as the real end of the input, rather than as an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored, without a parse error — including further, otherwise well-formed <abbr title="JavaScript Object Notation">JSON</abbr>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=p>);</span><span class=w> </span><span class=c1>// == 123, no error</span>
|
||||
<span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=s>"true"</span><span class=p>);</span><span class=w> </span><span class=c1>// == 123, the "true" is silently ignored too</span>
|
||||
</code></pre></div> <p>This is different from any other unexpected trailing byte, which <em>does</em> raise <a href=../exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"123x"</span><span class=p>);</span><span class=w> </span><span class=c1>// throws parse_error.101: unexpected additional data</span>
|
||||
</code></pre></div> <p>This falls out of the same convention used when no explicit input length is given at all: <code>json::parse(const char*)</code> already stops at the first NUL byte via <code>strlen()</code>, since a bare pointer has no length of its own. The library applies that same NUL-terminated-C-string convention uniformly, rather than only when a length is genuinely unavailable — so a <code>std::string</code>, iterator range, or container whose content happens to include a NUL byte is affected the same way a raw <code>const char*</code> would be.</p> <p>If your input may contain a trailing or embedded NUL that is <strong>not</strong> meant to signal the end of the <abbr title="JavaScript Object Notation">JSON</abbr> text — for instance, a fixed-size, zero-padded buffer — trim it yourself before calling <code>parse()</code>, since the library will otherwise silently stop there instead of raising an error:</p> <div class=highlight><pre><span></span><code><span class=n>s</span><span class=p>.</span><span class=n>resize</span><span class=p>(</span><span class=n>s</span><span class=p>.</span><span class=n>find</span><span class=p>(</span><span class=sc>'\0'</span><span class=p>));</span><span class=w> </span><span class=c1>// drop everything from the first NUL onward, if any</span>
|
||||
@@ -56,4 +56,4 @@
|
||||
|
||||
<span class=w> </span><span class=k>friend</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_json</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>Holder</span><span class=o>&</span><span class=w> </span><span class=n>h</span><span class=p>)</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=cm>/* ... */</span><span class=w> </span><span class=p>}</span>
|
||||
<span class=p>};</span>
|
||||
</code></pre></div> <p>The <a href=../../api/macros/nlohmann_define_type_intrusive/ ><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code></a> macros define hidden friends as well. See <a href="https://github.com/nlohmann/json/issues/3669">#3669</a> for details.</p> <h3 id=missing-stl-function>Missing <abbr title="Standard Template Library">STL</abbr> function<a class=headerlink href=#missing-stl-function title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why do I get a compilation error <code>'to_string' is not a member of 'std'</code> (or similarly, for <code>strtod</code> or <code>strtof</code>)?</li> <li>Why does the code not compile with MinGW or Android <abbr title="Software Development Kit">SDK</abbr>?</li> </ul> </div> <p>This is not an issue with the code, but rather with the compiler itself. On Android, use a current <abbr title="Native Development Kit">NDK</abbr> (see above). For MinGW, please refer to <a href="http://tehsausage.com/mingw-to-string">this site</a> and <a href="https://github.com/nlohmann/json/issues/136">this discussion</a> for information on how to fix this bug.</p> <!-- 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:46:13 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, CodLine truncated
|
||||
</code></pre></div> <p>The <a href=../../api/macros/nlohmann_define_type_intrusive/ ><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code></a> macros define hidden friends as well. See <a href="https://github.com/nlohmann/json/issues/3669">#3669</a> for details.</p> <h3 id=missing-stl-function>Missing <abbr title="Standard Template Library">STL</abbr> function<a class=headerlink href=#missing-stl-function title="Permanent link">¶</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why do I get a compilation error <code>'to_string' is not a member of 'std'</code> (or similarly, for <code>strtod</code> or <code>strtof</code>)?</li> <li>Why does the code not compile with MinGW or Android <abbr title="Software Development Kit">SDK</abbr>?</li> </ul> </div> <p>This is not an issue with the code, but rather with the compiler itself. On Android, use a current <abbr title="Native Development Kit">NDK</abbr> (see above). For MinGW, please refer to <a href="http://tehsausage.com/mingw-to-string">this site</a> and <a href="https://github.com/nlohmann/json/issues/136">this discussion</a> for information on how to fix this bug.</p> <!-- 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 17:17:57 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, CodLine truncated
|
||||
+1
-1
@@ -84,7 +84,7 @@ The library supports **Unicode input** as follows:
|
||||
- The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
|
||||
- Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
|
||||
- The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
|
||||
- When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
|
||||
- When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/index.md) may throw an exception unless `json::error_handler_t::replace`, `json::error_handler_t::ignore`, or `json::error_handler_t::keep` are used as error handlers.
|
||||
|
||||
In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or ISO 8859-1 is often the standard encoding.
|
||||
|
||||
|
||||
@@ -116,7 +116,7 @@ function to use instead.
|
||||
=== "Deprecated"
|
||||
|
||||
```cpp
|
||||
using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
|
||||
using my_json = nlohmann::json::with_string_t<my_string_type>;
|
||||
nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
|
||||
```
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>s</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>ptr</span><span class=p>;</span>
|
||||
</code></pre></div> </div> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>::</span><span class=n>json_pointer</span><span class=w> </span><span class=n>ptr</span><span class=p>(</span><span class=s>"/foo/bar/1"</span><span class=p>);</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>s</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>ptr</span><span class=p>.</span><span class=n>to_string</span><span class=p>();</span>
|
||||
</code></pre></div> </div> </div> </div> </li> <li> <p>Passing a <code>basic_json</code> specialization as template parameter <code>RefStringType</code> to <a href=../../api/json_pointer/ ><code>json_pointer</code></a> is deprecated since 3.11.0. The string type can now be directly provided. This also applies to passing such a <abbr title="JavaScript Object Notation">JSON</abbr> pointer to <a href=../../api/basic_json/at/ ><code>at</code></a>, <a href=../../api/basic_json/contains/ ><code>contains</code></a>, <a href=../../api/basic_json/operator%5B%5D/ ><code>operator[]</code></a>, and <a href=../../api/basic_json/value/ ><code>value</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=5:2><input checked=checked id=__tabbed_5_1 name=__tabbed_5 type=radio><input id=__tabbed_5_2 name=__tabbed_5 type=radio><div class=tabbed-labels><label for=__tabbed_5_1>Deprecated</label><label for=__tabbed_5_2>Future-proof</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=k>using</span><span class=w> </span><span class=n>my_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>basic_json</span><span class=o><</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span><span class=w> </span><span class=n>my_string_type</span><span class=o>></span><span class=p>;</span>
|
||||
</code></pre></div> </div> </div> </div> </li> <li> <p>Passing a <code>basic_json</code> specialization as template parameter <code>RefStringType</code> to <a href=../../api/json_pointer/ ><code>json_pointer</code></a> is deprecated since 3.11.0. The string type can now be directly provided. This also applies to passing such a <abbr title="JavaScript Object Notation">JSON</abbr> pointer to <a href=../../api/basic_json/at/ ><code>at</code></a>, <a href=../../api/basic_json/contains/ ><code>contains</code></a>, <a href=../../api/basic_json/operator%5B%5D/ ><code>operator[]</code></a>, and <a href=../../api/basic_json/value/ ><code>value</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=5:2><input checked=checked id=__tabbed_5_1 name=__tabbed_5 type=radio><input id=__tabbed_5_2 name=__tabbed_5 type=radio><div class=tabbed-labels><label for=__tabbed_5_1>Deprecated</label><label for=__tabbed_5_2>Future-proof</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=k>using</span><span class=w> </span><span class=n>my_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=o>::</span><span class=n>with_string_t</span><span class=o><</span><span class=n>my_string_type</span><span class=o>></span><span class=p>;</span>
|
||||
<span class=n>nlohmann</span><span class=o>::</span><span class=n>json_pointer</span><span class=o><</span><span class=n>my_json</span><span class=o>></span><span class=w> </span><span class=n>ptr</span><span class=p>(</span><span class=s>"/foo/bar/1"</span><span class=p>);</span>
|
||||
</code></pre></div> </div> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=n>nlohmann</span><span class=o>::</span><span class=n>json_pointer</span><span class=o><</span><span class=n>my_string_type</span><span class=o>></span><span class=w> </span><span class=n>ptr</span><span class=p>(</span><span class=s>"/foo/bar/1"</span><span class=p>);</span>
|
||||
</code></pre></div> </div> </div> </div> <p>Thereby, <code>my_json::json_pointer</code> is an alias for <code>nlohmann::json_pointer<my_string_type></code>; in general, <code>basic_json::json_pointer</code> is always an alias to the <code>json_pointer</code> with the appropriate string type for all specializations of <code>basic_json</code>.</p> </li> </ul> <h3 id=miscellaneous-functions>Miscellaneous functions<a class=headerlink href=#miscellaneous-functions title="Permanent link">¶</a></h3> <ul> <li> <p>The function <code>iterator_wrapper</code> is deprecated since 3.1.0. Please use the member function <a href=../../api/basic_json/items/ ><code>items</code></a> instead.</p> <div class="tabbed-set tabbed-alternate" data-tabs=6:2><input checked=checked id=__tabbed_6_1 name=__tabbed_6 type=radio><input id=__tabbed_6_2 name=__tabbed_6 type=radio><div class=tabbed-labels><label for=__tabbed_6_1>Deprecated</label><label for=__tabbed_6_2>Future-proof</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class=highlight><pre><span></span><code><span class=k>for</span><span class=w> </span><span class=p>(</span><span class=k>auto</span><span class=w> </span><span class=o>&</span><span class=n>x</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=o>::</span><span class=n>iterator_wrapper</span><span class=p>(</span><span class=n>j</span><span class=p>))</span>
|
||||
@@ -54,4 +54,4 @@
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>j</span><span class=p>[</span><span class=s>"age"</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </div> </div> </div> <h2 id=do-not-use-the-detail-namespace>Do not use the <code>detail</code> namespace<a class=headerlink href=#do-not-use-the-detail-namespace title="Permanent link">¶</a></h2> <p>The <code>nlohmann::detail</code> namespace is not part of the public <abbr title="Application Programming Interfaces">API</abbr> of the library and can change in any version without an announcement. Do not rely on any function or type in the <code>detail</code> namespace.</p> <!-- 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 20:11: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.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 - Line truncated
|
||||
</code></pre></div> </div> </div> </div> <h2 id=do-not-use-the-detail-namespace>Do not use the <code>detail</code> namespace<a class=headerlink href=#do-not-use-the-detail-namespace title="Permanent link">¶</a></h2> <p>The <code>nlohmann::detail</code> namespace is not part of the public <abbr title="Application Programming Interfaces">API</abbr> of the library and can change in any version without an announcement. Do not rely on any function or type in the <code>detail</code> namespace.</p> <!-- 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 8, 2026 14:11:16 UTC">October 8, 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 - Line truncated
|
||||
@@ -67,7 +67,7 @@ Define [`JSON_DELETE_DEPRECATED_FUNCTIONS`](https://json.nlohmann.me/api/macros/
|
||||
- Passing a `basic_json` specialization as template parameter `RefStringType` to [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly provided. This also applies to passing such a JSON pointer to [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md), [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), and [`value`](https://json.nlohmann.me/api/basic_json/value/index.md).
|
||||
|
||||
```
|
||||
using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
|
||||
using my_json = nlohmann::json::with_string_t<my_string_type>;
|
||||
nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
|
||||
```
|
||||
|
||||
|
||||
@@ -125,10 +125,24 @@ meson wrap install nlohmann_json
|
||||
Please see the Meson project for any issues regarding the packaging.
|
||||
|
||||
The provided `meson.build` can also be used as an alternative to CMake for installing `nlohmann_json` system-wide in
|
||||
which case a [pkg-config](pkg-config.md) file is installed. To use it, have your build system require the
|
||||
`nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the
|
||||
[`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than
|
||||
using the subproject directly.
|
||||
which case a [pkg-config](pkg-config.md) file and the CMake package config files are installed. To use it, have your build system require
|
||||
the `nlohmann_json` pkg-config dependency, or use [`find_package(nlohmann_json)`](cmake.md#external) in CMake. In Meson,
|
||||
it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a
|
||||
subproject fallback, rather than using the subproject directly.
|
||||
|
||||
The options that change the library's configuration are available in Meson as well, named like the
|
||||
[CMake options](cmake.md#cmake-options) without the `JSON_` prefix: `MultipleHeaders`, `GlobalUDLs`,
|
||||
`ImplicitConversions`, `DisableEnumSerialization`, `DisableTupleReferenceConversion`, `Diagnostics`,
|
||||
`Diagnostic_Positions`, `LegacyDiscardedValueComparison`, `StrictNulHandling`, `StrictBinaryUTF8`, and
|
||||
`DeleteDeprecatedFunctions`. They have the same defaults as in CMake, except that
|
||||
`MultipleHeaders` is `false`. Set them with `-D` when setting up the build, or with the subproject name as prefix when
|
||||
the library is used as a subproject:
|
||||
|
||||
```shell
|
||||
meson setup build -Dnlohmann_json:Diagnostics=true
|
||||
```
|
||||
|
||||
The resulting compile definitions are part of the Meson dependency, the pkg-config file, and the CMake target.
|
||||
|
||||
??? example "Example: Wrap"
|
||||
|
||||
|
||||
@@ -59,7 +59,8 @@
|
||||
</code></pre></div> </li> <li> <p>Compile the code and pass the Homebrew prefix to CMake to find installed packages via <code class=highlight><span class=err>find_package</span></code>:</p> <div class=highlight><pre><span></span><code><span class=nv>CMAKE_PREFIX_PATH</span><span class=o>=</span><span class=k>$(</span>brew<span class=w> </span>--prefix<span class=k>)</span><span class=w> </span>cmake<span class=w> </span>-S<span class=w> </span>.<span class=w> </span>-B<span class=w> </span>build
|
||||
cmake<span class=w> </span>--build<span class=w> </span>build
|
||||
</code></pre></div> </li> </ol> </details> <h2 id=meson>Meson<a class=headerlink href=#meson title="Permanent link">¶</a></h2> <div class="admonition abstract"> <p class=admonition-title>Summary</p> <p>wrap: <strong><code>nlohmann_json</code></strong></p> <ul> <li><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M7.75 6.5a1.25 1.25 0 1 0 0 2.5 1.25 1.25 0 0 0 0-2.5"/><path d="M2.5 1h8.44a1.5 1.5 0 0 1 1.06.44l10.25 10.25a1.5 1.5 0 0 1 0 2.12l-8.44 8.44a1.5 1.5 0 0 1-2.12 0L1.44 12A1.5 1.5 0 0 1 1 10.94V2.5A1.5 1.5 0 0 1 2.5 1m0 1.5v8.44l10.25 10.25 8.44-8.44L10.94 2.5Z"/></svg></span> Available versions: current version and select older versions (see <a href="https://mesonbuild.com/Wrapdb-projects.html">WrapDB</a>)</li> <li><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20.322.75h1.176a1.75 1.75 0 0 1 1.75 1.749v1.177a10.75 10.75 0 0 1-2.925 7.374l-1.228 1.304a24 24 0 0 1-1.596 1.542v5.038c0 .615-.323 1.184-.85 1.5l-4.514 2.709a.75.75 0 0 1-1.12-.488l-.963-4.572a1.3 1.3 0 0 1-.14-.129L8.04 15.96l-1.994-1.873a1.3 1.3 0 0 1-.129-.14l-4.571-.963a.75.75 0 0 1-.49-1.12l2.71-4.514c.316-.527.885-.85 1.5-.85h5.037a24 24 0 0 1 1.542-1.594l1.304-1.23A10.75 10.75 0 0 1 20.321.75Zm-6.344 4.018v-.001l-1.304 1.23a22.3 22.3 0 0 0-3.255 3.851l-2.193 3.29 1.859 1.744.034.034 1.743 1.858 3.288-2.192a22.3 22.3 0 0 0 3.854-3.257l1.228-1.303a9.25 9.25 0 0 0 2.517-6.346V2.5a.25.25 0 0 0-.25-.25h-1.177a9.25 9.25 0 0 0-6.344 2.518M6.5 21c-1.209 1.209-3.901 1.445-4.743 1.49a.24.24 0 0 1-.18-.067.24.24 0 0 1-.067-.18c.045-.842.281-3.534 1.49-4.743.9-.9 2.6-.9 3.5 0s.9 2.6 0 3.5m-.592-8.588L8.17 9.017q.346-.519.717-1.017H5.066a.25.25 0 0 0-.214.121l-2.167 3.612ZM16 15.112q-.5.372-1.018.718l-3.393 2.262.678 3.223 3.612-2.167a.25.25 0 0 0 .121-.214ZM17.5 8a1.5 1.5 0 1 1-3.001-.001A1.5 1.5 0 0 1 17.5 8"/></svg></span> The package is updated automatically from file <a href="https://github.com/nlohmann/json/blob/develop/meson.build"><code>meson.build</code></a>.</li> <li><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 3a2 2 0 0 1 2-2h9.982a2 2 0 0 1 1.414.586l4.018 4.018A2 2 0 0 1 21 7.018V21a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2Zm2-.5a.5.5 0 0 0-.5.5v18a.5.5 0 0 0 .5.5h14a.5.5 0 0 0 .5-.5V8.5h-4a2 2 0 0 1-2-2v-4Zm10 0v4a.5.5 0 0 0 .5.5h4a.5.5 0 0 0-.146-.336l-4.018-4.018A.5.5 0 0 0 15 2.5"/></svg></span> File issues at the <a href="https://github.com/nlohmann/json/issues">library issue tracker</a></li> <li><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10.97 8.265a1.45 1.45 0 0 0-.487.57.75.75 0 0 1-1.341-.67c.2-.402.513-.826.997-1.148C10.627 6.69 11.244 6.5 12 6.5c.658 0 1.369.195 1.934.619a2.45 2.45 0 0 1 1.004 2.006c0 1.033-.513 1.72-1.027 2.215-.19.183-.399.358-.579.508l-.147.123a4 4 0 0 0-.435.409v1.37a.75.75 0 1 1-1.5 0v-1.473c0-.237.067-.504.247-.736.22-.28.486-.517.718-.714l.183-.153.001-.001c.172-.143.324-.27.47-.412.368-.355.569-.676.569-1.136a.95.95 0 0 0-.404-.806C12.766 8.118 12.384 8 12 8c-.494 0-.814.121-1.03.265M13 17a1 1 0 1 1-2 0 1 1 0 0 1 2 0"/><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1M2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12"/></svg></span> <a href="https://mesonbuild.com/index.html">Meson website</a></li> </ul> </div> <p>If you are using the <a href="http://mesonbuild.com">Meson Build System</a>, add this source tree as a <a href="https://mesonbuild.com/Subprojects.html#using-a-subproject">meson subproject</a>. You may also use the <code>include.zip</code> published in this project's <a href="https://github.com/nlohmann/json/releases">Releases</a> to reduce the size of the vendored source tree. Alternatively, you can get a wrap file by downloading it from <a href="https://mesonbuild.com/Wrapdb-projects.html">Meson WrapDB</a>, or use</p> <div class=highlight><pre><span></span><code>meson<span class=w> </span>wrap<span class=w> </span>install<span class=w> </span>nlohmann_json
|
||||
</code></pre></div> <p>Please see the Meson project for any issues regarding the packaging.</p> <p>The provided <code>meson.build</code> can also be used as an alternative to CMake for installing <code>nlohmann_json</code> system-wide in which case a <a href=../pkg-config/ >pkg-config</a> file is installed. To use it, have your build system require the <code>nlohmann_json</code> pkg-config dependency. In Meson, it is preferred to use the <a href="https://mesonbuild.com/Reference-manual.html#dependency"><code>dependency()</code></a> object with a subproject fallback, rather than using the subproject directly.</p> <details class=example> <summary>Example: Wrap</summary> <ol> <li> <p>Create the following files:</p> <div class=highlight><span class=filename>meson.build</span><pre><span></span><code><span class=na>project('json_example', 'cpp',</span>
|
||||
</code></pre></div> <p>Please see the Meson project for any issues regarding the packaging.</p> <p>The provided <code>meson.build</code> can also be used as an alternative to CMake for installing <code>nlohmann_json</code> system-wide in which case a <a href=../pkg-config/ >pkg-config</a> file and the CMake package config files are installed. To use it, have your build system require the <code>nlohmann_json</code> pkg-config dependency, or use <a href=../cmake/#external><code>find_package(nlohmann_json)</code></a> in CMake. In Meson, it is preferred to use the <a href="https://mesonbuild.com/Reference-manual.html#dependency"><code>dependency()</code></a> object with a subproject fallback, rather than using the subproject directly.</p> <p>The options that change the library's configuration are available in Meson as well, named like the <a href=../cmake/#cmake-options>CMake options</a> without the <code>JSON_</code> prefix: <code>MultipleHeaders</code>, <code>GlobalUDLs</code>, <code>ImplicitConversions</code>, <code>DisableEnumSerialization</code>, <code>DisableTupleReferenceConversion</code>, <code>Diagnostics</code>, <code>Diagnostic_Positions</code>, <code>LegacyDiscardedValueComparison</code>, <code>StrictNulHandling</code>, <code>StrictBinaryUTF8</code>, and <code>DeleteDeprecatedFunctions</code>. They have the same defaults as in CMake, except that <code>MultipleHeaders</code> is <code>false</code>. Set them with <code>-D</code> when setting up the build, or with the subproject name as prefix when the library is used as a subproject:</p> <div class=highlight><pre><span></span><code>meson<span class=w> </span>setup<span class=w> </span>build<span class=w> </span>-Dnlohmann_json:Diagnostics<span class=o>=</span><span class=nb>true</span>
|
||||
</code></pre></div> <p>The resulting compile definitions are part of the Meson dependency, the pkg-config file, and the CMake target.</p> <details class=example> <summary>Example: Wrap</summary> <ol> <li> <p>Create the following files:</p> <div class=highlight><span class=filename>meson.build</span><pre><span></span><code><span class=na>project('json_example', 'cpp',</span>
|
||||
<span class=w> </span><span class=na>version</span><span class=o>:</span><span class=w> </span><span class=s>'1.0'</span><span class=na>,</span>
|
||||
<span class=w> </span><span class=na>default_options</span><span class=o>:</span><span class=w> </span><span class=s>['cpp_std=c++11']</span>
|
||||
<span class=na>)</span>
|
||||
@@ -451,4 +452,4 @@ cmake<span class=w> </span>--build<span class=w> </span>build
|
||||
<span class=w> </span><span class=nf>set_languages</span><span class=p>(</span><span class=s2>"cxx11"</span><span class=p>)</span>
|
||||
</code></pre></div> </li> <li> <p>Build</p> <div class=highlight><pre><span></span><code>xmake
|
||||
</code></pre></div> </li> <li> <p>Run</p> <div class=highlight><pre><span></span><code>xmake<span class=w> </span>run
|
||||
</code></pre></div> </li> </ol> </details> <hr> <h2 id=other-package-managers>Other package managers<a class=headerlink href=#other-package-managers title="Permanent link">¶</a></h2> <p>The library is also contained in many other package repositories; <a href="https://repology.org/project/nlohmann-json/versions">Repology</a> tracks the packaged versions across repositories.</p> <hr> <h2 id=buckaroo>Buckaroo<a class=headerlink href=#buckaroo title="Permanent link">¶</a></h2> <p>If you are using <a href="https://github.com/LoopPerfect/buckaroo">Buckaroo</a>, you can install this library's module with <code>buckaroo add github.com/buckaroo-pm/nlohmann-json</code>. There is a demo repo <a href="https://github.com/njlr/buckaroo-nholmann-json-example">here</a>.</p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://github.com/buckaroo-pm/nlohmann-json">repository</a> has not been updated in years.</p> </div> <h2 id=cocoapods>CocoaPods<a class=headerlink href=#cocoapods title="Permanent link">¶</a></h2> <p>If you are using <a href="https://cocoapods.org">CocoaPods</a>, you can use the library by adding pod <code>"nlohmann_json", '~>3.1.2'</code> to your podfile (see <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">an example</a>). Please file issues at <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">the repository</a>, as its issue tracker is no longer reachable.</p> <p><a href="https://cocoapods.org/pods/nlohmann_json"><img alt="CocoaPods package" src="../../assets/external/img.shields.io/cocoapods/v/nlohmann_json.svg"></a></p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://cocoapods.org/pods/nlohmann_json">pod</a> has not been updated in years.</p> </div> <h2 id=npm>npm<a class=headerlink href=#npm title="Permanent link">¶</a></h2> <p>This project does not publish an official <a href="https://www.npmjs.com">npm</a> package. The npm package <a href="https://www.npmjs.com/package/nlohmann-json"><code>nlohmann-json</code></a> (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.</p> <h2 id=esp-idf-and-platformio>ESP-IDF and PlatformIO<a class=headerlink href=#esp-idf-and-platformio title="Permanent link">¶</a></h2> <p>There is no official package published to the <a href="https://components.espressif.com">ESP-IDF Component Registry</a> or the <a href="https://registry.platformio.org">PlatformIO Registry</a>. A community-maintained fork, <a href="https://github.com/Johboh/nlohmann-json">Johboh/nlohmann-json</a>, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its <code>include/</code> directory to your component's/project's include paths, like any other integration method described on this page.</p> <!-- 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 2, 2026 09:32:15 UTC">October 2, 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="_blaLine truncated
|
||||
</code></pre></div> </li> </ol> </details> <hr> <h2 id=other-package-managers>Other package managers<a class=headerlink href=#other-package-managers title="Permanent link">¶</a></h2> <p>The library is also contained in many other package repositories; <a href="https://repology.org/project/nlohmann-json/versions">Repology</a> tracks the packaged versions across repositories.</p> <hr> <h2 id=buckaroo>Buckaroo<a class=headerlink href=#buckaroo title="Permanent link">¶</a></h2> <p>If you are using <a href="https://github.com/LoopPerfect/buckaroo">Buckaroo</a>, you can install this library's module with <code>buckaroo add github.com/buckaroo-pm/nlohmann-json</code>. There is a demo repo <a href="https://github.com/njlr/buckaroo-nholmann-json-example">here</a>.</p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://github.com/buckaroo-pm/nlohmann-json">repository</a> has not been updated in years.</p> </div> <h2 id=cocoapods>CocoaPods<a class=headerlink href=#cocoapods title="Permanent link">¶</a></h2> <p>If you are using <a href="https://cocoapods.org">CocoaPods</a>, you can use the library by adding pod <code>"nlohmann_json", '~>3.1.2'</code> to your podfile (see <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">an example</a>). Please file issues at <a href="https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/">the repository</a>, as its issue tracker is no longer reachable.</p> <p><a href="https://cocoapods.org/pods/nlohmann_json"><img alt="CocoaPods package" src="../../assets/external/img.shields.io/cocoapods/v/nlohmann_json.svg"></a></p> <div class="admonition warning"> <p class=admonition-title>Warning</p> <p>The module is outdated as the respective <a href="https://cocoapods.org/pods/nlohmann_json">pod</a> has not been updated in years.</p> </div> <h2 id=npm>npm<a class=headerlink href=#npm title="Permanent link">¶</a></h2> <p>This project does not publish an official <a href="https://www.npmjs.com">npm</a> package. The npm package <a href="https://www.npmjs.com/package/nlohmann-json"><code>nlohmann-json</code></a> (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.</p> <h2 id=esp-idf-and-platformio>ESP-IDF and PlatformIO<a class=headerlink href=#esp-idf-and-platformio title="Permanent link">¶</a></h2> <p>There is no official package published to the <a href="https://components.espressif.com">ESP-IDF Component Registry</a> or the <a href="https://registry.platformio.org">PlatformIO Registry</a>. A community-maintained fork, <a href="https://github.com/Johboh/nlohmann-json">Johboh/nlohmann-json</a>, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its <code>include/</code> directory to your component's/project's include paths, like any other integration method described on this page.</p> <!-- 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 20:20: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="_blaLine truncated
|
||||
@@ -161,7 +161,15 @@ meson wrap install nlohmann_json
|
||||
|
||||
Please see the Meson project for any issues regarding the packaging.
|
||||
|
||||
The provided `meson.build` can also be used as an alternative to CMake for installing `nlohmann_json` system-wide in which case a [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) file is installed. To use it, have your build system require the `nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
|
||||
The provided `meson.build` can also be used as an alternative to CMake for installing `nlohmann_json` system-wide in which case a [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) file and the CMake package config files are installed. To use it, have your build system require the `nlohmann_json` pkg-config dependency, or use [`find_package(nlohmann_json)`](https://json.nlohmann.me/integration/cmake/#external) in CMake. In Meson, it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
|
||||
|
||||
The options that change the library's configuration are available in Meson as well, named like the [CMake options](https://json.nlohmann.me/integration/cmake/#cmake-options) without the `JSON_` prefix: `MultipleHeaders`, `GlobalUDLs`, `ImplicitConversions`, `DisableEnumSerialization`, `DisableTupleReferenceConversion`, `Diagnostics`, `Diagnostic_Positions`, `LegacyDiscardedValueComparison`, `StrictNulHandling`, `StrictBinaryUTF8`, and `DeleteDeprecatedFunctions`. They have the same defaults as in CMake, except that `MultipleHeaders` is `false`. Set them with `-D` when setting up the build, or with the subproject name as prefix when the library is used as a subproject:
|
||||
|
||||
```
|
||||
meson setup build -Dnlohmann_json:Diagnostics=true
|
||||
```
|
||||
|
||||
The resulting compile definitions are part of the Meson dependency, the pkg-config file, and the CMake target.
|
||||
|
||||
Example: Wrap
|
||||
|
||||
|
||||
@@ -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
|
||||
+276
-276
File diff suppressed because it is too large.
Load diff
Binary file not shown.
Reference in new issue
Block a user