mirror of
https://github.com/nlohmann/json.git
synced 2026-11-07 13:09:21 +00:00
deploy: 18138227dc
This commit is contained in:
1 parent
5531ec9380
commit
cf8df97ba7
12 files changed
+440
-428
No files matched your search
@@ -5,7 +5,9 @@
|
||||
```
|
||||
|
||||
When defined to `1`, parsing from a `#!cpp FILE*` reads every character with `std::fgetc`, as in version 3.12.0 and
|
||||
earlier, instead of locking the file once and reading it with the unlocked stdio functions.
|
||||
earlier, instead of locking the file once and reading it with the unlocked stdio functions. This also turns off the
|
||||
scan of the `FILE`'s buffer in bulk (see below), which [`JSON_DISABLE_STREAM_BULK_SCAN`](json_disable_stream_bulk_scan.md)
|
||||
does not affect.
|
||||
|
||||
It does not change any result: values, exceptions, and the position of the file after parsing are the same either way.
|
||||
Only the speed and the locking of the file differ (see the notes on locking below).
|
||||
@@ -37,9 +39,17 @@ The default value is `0`: the file is locked once and read with the unlocked std
|
||||
| Microsoft (MSVC, clang-cl) | `_lock_file`, `_fgetc_nolock`, `_unlock_file` |
|
||||
| others (e.g., musl, MinGW, newlib) | `std::fgetc`, as before |
|
||||
|
||||
This makes parsing from a `FILE*` 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with
|
||||
glibc, whose locking is cheaper. The binary formats ([`from_cbor`](../basic_json/from_cbor.md),
|
||||
[`from_msgpack`](../basic_json/from_msgpack.md), ...) read from a `FILE*` the same way.
|
||||
With glibc and the Apple C library, the parser also scans the characters that the `FILE` already holds in its
|
||||
buffer in bulk, as it scans the get area of a stream (see
|
||||
[`JSON_DISABLE_STREAM_BULK_SCAN`](json_disable_stream_bulk_scan.md)): it reads the same fields of the `FILE` that
|
||||
the C library's own `getc_unlocked` reads, and it consumes exactly the characters that `getc_unlocked` would have
|
||||
returned, so the file is left where it was left before.
|
||||
|
||||
Locking the file once makes parsing from a `FILE*` 3 to 4 times as fast with the Apple C library and 1.1 to 1.3
|
||||
times as fast with glibc, whose locking is cheaper. Scanning the buffer in bulk makes `parse()` another 1.7 to 2.6
|
||||
times as fast (and `accept()` 2.9 to 4.4 times), about as fast as parsing from a `std::ifstream`. The binary
|
||||
formats ([`from_cbor`](../basic_json/from_cbor.md), [`from_msgpack`](../basic_json/from_msgpack.md), ...) read
|
||||
from a `FILE*` the same way.
|
||||
|
||||
!!! note "Locking"
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
<!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=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/" rel="canonical"><link href=../json_disable_tuple_reference_conversion/ rel=prev><link href=../json_has_cpp_11/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>JSON_DISABLE_UNLOCKED_FILE_IO - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.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=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#json_disable_unlocked_file_io class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> JSON_DISABLE_UNLOCKED_FILE_IO </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom 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=custom data-md-color-accent=custom 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-icoLine truncated
|
||||
</code></pre></div> <p>When defined to <code>1</code>, parsing from a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> reads every character with <code>std::fgetc</code>, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions.</p> <p>It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).</p> <p>Builds with MemorySanitizer use <code>std::fgetc</code> automatically, because the inline <code>getc_unlocked</code> of glibc reads the stdio buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.</p> <h2 id=default-definition>Default definition<a class=headerlink href=#default-definition title="Permanent link">¶</a></h2> <p>The default value is <code>0</code>: the file is locked once and read with the unlocked stdio functions where they are available.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_UNLOCKED_FILE_IO 0</span>
|
||||
</code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition note"> <p class=admonition-title>Background</p> <p>The C standard library makes every <code>std::fgetc</code> call thread-safe by locking and unlocking the <code>FILE</code> object. When parsing from a <code>FILE*</code>, the parser reads one character at a time, so this happens for every character of the input.</p> <p>Instead, the parser locks the file once when parsing starts and unlocks it when parsing ends - also when an exception is thrown - and reads the characters in between without locking:</p> <table> <thead> <tr> <th>C library</th> <th>functions</th> </tr> </thead> <tbody> <tr> <td>glibc (Linux), Apple (macOS, iOS), Android, FreeBSD, NetBSD, OpenBSD, DragonFly BSD</td> <td><code>flockfile</code>, <code>getc_unlocked</code>, <code>funlockfile</code> (POSIX)</td> </tr> <tr> <td>Microsoft (<abbr title="Microsoft Visual C++">MSVC</abbr>, clang-cl)</td> <td><code>_lock_file</code>, <code>_fgetc_nolock</code>, <code>_unlock_file</code></td> </tr> <tr> <td>others (e.g., musl, <abbr title="Minimalist GNU for Windows">MinGW</abbr>, newlib)</td> <td><code>std::fgetc</code>, as before</td> </tr> </tbody> </table> <p>This makes parsing from a <code>FILE*</code> 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with glibc, whose locking is cheaper. The binary formats (<a href=../../basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../basic_json/from_msgpack/ ><code>from_msgpack</code></a>, ...) read from a <code>FILE*</code> the same way.</p> </div> <div class="admonition note"> <p class=admonition-title>Locking</p> <p>While a value is parsed from a <code>FILE*</code>, the parsing thread holds the file's lock. The lock is recursive, so the parsing thread itself - for instance, a <a href=../../json_sax/ ><abbr title="Simple API for XML">SAX</abbr></a> handler or a <a href=../../basic_json/parser_callback_t/ >parser callback</a> - can keep using the file with stdio functions such as <code>std::ftell</code>. Other threads that use the same <code>FILE</code> object wait until the parser is done. Before, they could interleave their reads with the parser's, which made the parsed input unpredictable anyway.</p> <p>A program in which a <abbr title="Simple API for XML">SAX</abbr> handler or parser callback waits for <strong>another</strong> thread that uses the <strong>same</strong> <code>FILE</code> object would deadlock. Define the macro to <code>1</code> for such programs.</p> </div> <div class="admonition note"> <p class=admonition-title><abbr title="Application Binary Interface">ABI</abbr> compatibility</p> <p>The value of this macro is encoded in the <a href=../../../features/namespace/ >namespace</a> (tag <code>_dufio</code>), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (<abbr title="One Definition Rule">ODR</abbr>) violations, but they cannot exchange instances of library types.</p> </div> <div class="admonition note"> <p class=admonition-title>Other inputs</p> <p>Reading from a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> is not affected by this macro; see <a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> for that input.</p> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: parsing from a <code>FILE*</code> (default)</summary> <p>The file is locked once while it is parsed:</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><cstdio></span>
|
||||
</code></pre></div> <p>When defined to <code>1</code>, parsing from a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> reads every character with <code>std::fgetc</code>, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions. This also turns off the scan of the <code>FILE</code>'s buffer in bulk (see below), which <a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> does not affect.</p> <p>It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).</p> <p>Builds with MemorySanitizer use <code>std::fgetc</code> automatically, because the inline <code>getc_unlocked</code> of glibc reads the stdio buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.</p> <h2 id=default-definition>Default definition<a class=headerlink href=#default-definition title="Permanent link">¶</a></h2> <p>The default value is <code>0</code>: the file is locked once and read with the unlocked stdio functions where they are available.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_UNLOCKED_FILE_IO 0</span>
|
||||
</code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition note"> <p class=admonition-title>Background</p> <p>The C standard library makes every <code>std::fgetc</code> call thread-safe by locking and unlocking the <code>FILE</code> object. When parsing from a <code>FILE*</code>, the parser reads one character at a time, so this happens for every character of the input.</p> <p>Instead, the parser locks the file once when parsing starts and unlocks it when parsing ends - also when an exception is thrown - and reads the characters in between without locking:</p> <table> <thead> <tr> <th>C library</th> <th>functions</th> </tr> </thead> <tbody> <tr> <td>glibc (Linux), Apple (macOS, iOS), Android, FreeBSD, NetBSD, OpenBSD, DragonFly BSD</td> <td><code>flockfile</code>, <code>getc_unlocked</code>, <code>funlockfile</code> (POSIX)</td> </tr> <tr> <td>Microsoft (<abbr title="Microsoft Visual C++">MSVC</abbr>, clang-cl)</td> <td><code>_lock_file</code>, <code>_fgetc_nolock</code>, <code>_unlock_file</code></td> </tr> <tr> <td>others (e.g., musl, <abbr title="Minimalist GNU for Windows">MinGW</abbr>, newlib)</td> <td><code>std::fgetc</code>, as before</td> </tr> </tbody> </table> <p>With glibc and the Apple C library, the parser also scans the characters that the <code>FILE</code> already holds in its buffer in bulk, as it scans the get area of a stream (see <a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a>): it reads the same fields of the <code>FILE</code> that the C library's own <code>getc_unlocked</code> reads, and it consumes exactly the characters that <code>getc_unlocked</code> would have returned, so the file is left where it was left before.</p> <p>Locking the file once makes parsing from a <code>FILE*</code> 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with glibc, whose locking is cheaper. Scanning the buffer in bulk makes <code>parse()</code> another 1.7 to 2.6 times as fast (and <code>accept()</code> 2.9 to 4.4 times), about as fast as parsing from a <code>std::ifstream</code>. The binary formats (<a href=../../basic_json/from_cbor/ ><code>from_cbor</code></a>, <a href=../../basic_json/from_msgpack/ ><code>from_msgpack</code></a>, ...) read from a <code>FILE*</code> the same way.</p> </div> <div class="admonition note"> <p class=admonition-title>Locking</p> <p>While a value is parsed from a <code>FILE*</code>, the parsing thread holds the file's lock. The lock is recursive, so the parsing thread itself - for instance, a <a href=../../json_sax/ ><abbr title="Simple API for XML">SAX</abbr></a> handler or a <a href=../../basic_json/parser_callback_t/ >parser callback</a> - can keep using the file with stdio functions such as <code>std::ftell</code>. Other threads that use the same <code>FILE</code> object wait until the parser is done. Before, they could interleave their reads with the parser's, which made the parsed input unpredictable anyway.</p> <p>A program in which a <abbr title="Simple API for XML">SAX</abbr> handler or parser callback waits for <strong>another</strong> thread that uses the <strong>same</strong> <code>FILE</code> object would deadlock. Define the macro to <code>1</code> for such programs.</p> </div> <div class="admonition note"> <p class=admonition-title><abbr title="Application Binary Interface">ABI</abbr> compatibility</p> <p>The value of this macro is encoded in the <a href=../../../features/namespace/ >namespace</a> (tag <code>_dufio</code>), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (<abbr title="One Definition Rule">ODR</abbr>) violations, but they cannot exchange instances of library types.</p> </div> <div class="admonition note"> <p class=admonition-title>Other inputs</p> <p>Reading from a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> is not affected by this macro; see <a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> for that input.</p> </div> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">¶</a></h2> <details class=example> <summary>Example: parsing from a <code>FILE*</code> (default)</summary> <p>The file is locked once while it is parsed:</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><cstdio></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>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
@@ -23,4 +23,4 @@
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span><span class=w> </span><span class=c1>// std::fgetc for every character</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>fclose</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> - read a <code>std::istream</code> one character at a time</li> <li><a href=../../../features/parsing/#input-sources-and-performance>Parsing: input sources and performance</a> - how input sources affect parsing performance</li> <li><a href=../../../features/parsing/large_and_partial_input/ >Large, Streamed, and Partial Input</a> - chunked, concatenated, and very large input</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </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 27, 2026 06:41:42 UTC">October 27, 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> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../json_disable_tuple_reference_conversion/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON_DISABLE_TUPLE_REFERENCE_CONVERSION"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON_DISABLE_TUPLE_REFERENCE_CONVERSION </div> </div> </a> <a href=../json_has_cpp_11/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26 </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <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 Line truncated
|
||||
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=../json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> - read a <code>std::istream</code> one character at a time</li> <li><a href=../../../features/parsing/#input-sources-and-performance>Parsing: input sources and performance</a> - how input sources affect parsing performance</li> <li><a href=../../../features/parsing/large_and_partial_input/ >Large, Streamed, and Partial Input</a> - chunked, concatenated, and very large input</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </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="November 7, 2026 09:11:09 UTC">November 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> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../json_disable_tuple_reference_conversion/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON_DISABLE_TUPLE_REFERENCE_CONVERSION"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON_DISABLE_TUPLE_REFERENCE_CONVERSION </div> </div> </a> <a href=../json_has_cpp_11/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26 </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <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 Line truncated
|
||||
@@ -4,7 +4,7 @@
|
||||
#define JSON_DISABLE_UNLOCKED_FILE_IO /* value */
|
||||
```
|
||||
|
||||
When defined to `1`, parsing from a `FILE*` reads every character with `std::fgetc`, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions.
|
||||
When defined to `1`, parsing from a `FILE*` reads every character with `std::fgetc`, as in version 3.12.0 and earlier, instead of locking the file once and reading it with the unlocked stdio functions. This also turns off the scan of the `FILE`'s buffer in bulk (see below), which [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md) does not affect.
|
||||
|
||||
It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).
|
||||
|
||||
@@ -32,7 +32,9 @@ Instead, the parser locks the file once when parsing starts and unlocks it when
|
||||
| Microsoft (MSVC, clang-cl) | `_lock_file`, `_fgetc_nolock`, `_unlock_file` |
|
||||
| others (e.g., musl, MinGW, newlib) | `std::fgetc`, as before |
|
||||
|
||||
This makes parsing from a `FILE*` 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with glibc, whose locking is cheaper. The binary formats ([`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md), [`from_msgpack`](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md), ...) read from a `FILE*` the same way.
|
||||
With glibc and the Apple C library, the parser also scans the characters that the `FILE` already holds in its buffer in bulk, as it scans the get area of a stream (see [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md)): it reads the same fields of the `FILE` that the C library's own `getc_unlocked` reads, and it consumes exactly the characters that `getc_unlocked` would have returned, so the file is left where it was left before.
|
||||
|
||||
Locking the file once makes parsing from a `FILE*` 3 to 4 times as fast with the Apple C library and 1.1 to 1.3 times as fast with glibc, whose locking is cheaper. Scanning the buffer in bulk makes `parse()` another 1.7 to 2.6 times as fast (and `accept()` 2.9 to 4.4 times), about as fast as parsing from a `std::ifstream`. The binary formats ([`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md), [`from_msgpack`](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md), ...) read from a `FILE*` the same way.
|
||||
|
||||
Locking
|
||||
|
||||
|
||||
+1
-1
@@ -77,7 +77,7 @@ them faster than others:
|
||||
|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
|
||||
| strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory | the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time |
|
||||
| `#!cpp std::istream` (`#!cpp std::ifstream`, `#!cpp std::istringstream`, ...) | the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up |
|
||||
| `#!cpp FILE*` | one character at a time, with the file locked once for the whole parse |
|
||||
| `#!cpp FILE*` | with glibc and the Apple C library, the characters the `FILE` holds in its buffer are scanned in bulk like a stream's; elsewhere one character at a time; the file is locked once for the whole parse |
|
||||
| other iterator ranges (e.g., `#!cpp std::list<char>`, `#!cpp std::istreambuf_iterator<char>`), wide strings | one character at a time |
|
||||
|
||||
Parsing a file from a `#!cpp std::ifstream` is therefore only about 10 to 20 % slower than reading the whole file into a
|
||||
|
||||
@@ -10,8 +10,8 @@
|
||||
<span class=c1>// parse from a file</span>
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>f</span><span class=p>(</span><span class=s>"example.json"</span><span class=p>);</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=n>data</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
|
||||
</code></pre></div> <p>See <a href=../files/ >Reading and writing files</a> for checking that the file was opened and for writing files safely.</p> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. The exception is wide-character input, which is read as <abbr title="Unicode Transformation Format">UTF</abbr>-16 or <abbr title="Unicode Transformation Format">UTF</abbr>-32 — depending on the character type — and converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8; see the <a href=../../api/basic_json/parse/ ><code>parse</code></a> page for an example. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format; input that arrives in chunks or contains several values is covered in <a href=large_and_partial_input/ >Large, streamed, and partial input</a>.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <p><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> accepts the same inputs with the same options, but keeps the result in a document rather than in a <code>basic_json</code> value; see <a href=#documents-and-views>Documents and views</a> below.</p> <h2 id=strictness-and-trailing-data>Strictness and trailing data<a class=headerlink href=#strictness-and-trailing-data title="Permanent link">¶</a></h2> <p><a href=../../api/basic_json/parse/ ><code>parse</code></a> reads a single <abbr title="JavaScript Object Notation">JSON</abbr> value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete <abbr title="JavaScript Object Notation">JSON</abbr> document.</p> <p><a href=../../api/operator_gtgt/ ><code>operator>></code></a> follows relaxed <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> semantics instead: it parses one <abbr title="JavaScript Object Notation">JSON</abbr> value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one <abbr title="JavaScript Object Notation">JSON</abbr> document, prefer <code>parse</code>.</p> <p>When using <code>operator>></code> to read several concatenated values this way, a value that is a number must be followed by whitespace, because <code>operator>></code> consumes the character that terminates a number, unless <a href=../../api/macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code> — see the <a href=../../api/operator_gtgt/#notes><code>operator>></code> notes</a> for details and examples.</p> <h2 id=input-sources-and-performance>Input sources and performance<a class=headerlink href=#input-sources-and-performance title="Permanent link">¶</a></h2> <p>All inputs produce the same values and the same exceptions, but they are read in different ways, which makes some of them faster than others:</p> <table> <thead> <tr> <th>input</th> <th>how it is read</th> </tr> </thead> <tbody> <tr> <td>strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory</td> <td>the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span></code>, ...)</td> <td>the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up</td> </tr> <tr> <td><code class=highlight><span class=kt>FILE</span><span class=o>*</span></code></td> <td>one character at a time, with the file locked once for the whole parse</td> </tr> <tr> <td>other iterator ranges (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</span><span class=o><</span><span class=kt>char</span><span class=o>></span></code>, <code class=highlight><span class=n>std</span><span Line truncated
|
||||
</code></pre></div> <p>See <a href=../files/ >Reading and writing files</a> for checking that the file was opened and for writing files safely.</p> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. The exception is wide-character input, which is read as <abbr title="Unicode Transformation Format">UTF</abbr>-16 or <abbr title="Unicode Transformation Format">UTF</abbr>-32 — depending on the character type — and converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8; see the <a href=../../api/basic_json/parse/ ><code>parse</code></a> page for an example. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format; input that arrives in chunks or contains several values is covered in <a href=large_and_partial_input/ >Large, streamed, and partial input</a>.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <p><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> accepts the same inputs with the same options, but keeps the result in a document rather than in a <code>basic_json</code> value; see <a href=#documents-and-views>Documents and views</a> below.</p> <h2 id=strictness-and-trailing-data>Strictness and trailing data<a class=headerlink href=#strictness-and-trailing-data title="Permanent link">¶</a></h2> <p><a href=../../api/basic_json/parse/ ><code>parse</code></a> reads a single <abbr title="JavaScript Object Notation">JSON</abbr> value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete <abbr title="JavaScript Object Notation">JSON</abbr> document.</p> <p><a href=../../api/operator_gtgt/ ><code>operator>></code></a> follows relaxed <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> semantics instead: it parses one <abbr title="JavaScript Object Notation">JSON</abbr> value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one <abbr title="JavaScript Object Notation">JSON</abbr> document, prefer <code>parse</code>.</p> <p>When using <code>operator>></code> to read several concatenated values this way, a value that is a number must be followed by whitespace, because <code>operator>></code> consumes the character that terminates a number, unless <a href=../../api/macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code> — see the <a href=../../api/operator_gtgt/#notes><code>operator>></code> notes</a> for details and examples.</p> <h2 id=input-sources-and-performance>Input sources and performance<a class=headerlink href=#input-sources-and-performance title="Permanent link">¶</a></h2> <p>All inputs produce the same values and the same exceptions, but they are read in different ways, which makes some of them faster than others:</p> <table> <thead> <tr> <th>input</th> <th>how it is read</th> </tr> </thead> <tbody> <tr> <td>strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory</td> <td>the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span></code>, ...)</td> <td>the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up</td> </tr> <tr> <td><code class=highlight><span class=kt>FILE</span><span class=o>*</span></code></td> <td>with glibc and the Apple C library, the characters the <code>FILE</code> holds in its buffer are scanned in bulk like a stream's; elsewhere one character at a time; the file is locked once for the whole parse</td> </tr> <tr> <td>other iterator ranges (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</spanLine truncated
|
||||
|
||||
<span class=n>json_document</span><span class=w> </span><span class=n>doc</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json_document</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span><span class=s>{"happy": true, "pi": 3.141}</span><span class=dl>)</span><span class=s>"</span><span class=p>);</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>doc</span><span class=p>.</span><span class=n>root</span><span class=p>()[</span><span class=s>"happy"</span><span class=p>].</span><span class=n>get</span><span class=o><</span><span class=kt>bool</span><span class=o>></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>
|
||||
</code></pre></div> <p>See <a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> for the concept and the trade-offs.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>When the input is not valid <abbr title="JavaScript Object Notation">JSON</abbr>, the <code>parse</code> function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or <a href=../../api/basic_json/accept/ ><code>accept</code></a> can be used to only check whether an input is valid <abbr title="JavaScript Object Notation">JSON</abbr>. See <a href=parse_exceptions/ >parsing and exceptions</a> for the available options.</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/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> - deserialize into a document instead of a value</li> <li><a href=../../api/basic_json/accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> - parse newline-delimited <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=large_and_partial_input/ >Large, streamed, and partial input</a> - chunked, concatenated, and very large input</li> <li><a href=parser_callbacks/ >parser callbacks</a> - influence the parsing by a callback function</li> <li><a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - implement a custom <abbr title="Simple API for XML">SAX</abbr> handler</li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - parse into a read-only document and read it through views</li> <li><a href=parse_exceptions/ >parsing and exceptions</a> - control error handling</li> <li><a href=untrusted_input/ >parsing untrusted input</a> - what to consider when parsing input from untrusted sources</li> <li><a href=../../api/operator_gtgt/ ><code>operator>></code></a> - deserialize from stream</li> <li><a href=../../api/json_sax/ ><code>json_sax</code></a> - documentation of the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../api/basic_json/parse_error/ ><code>parse_error</code></a> - exception thrown on a parse error</li> <li><a href=../comments/ >Comments</a> - ignore <code>//</code> and <code>/* */</code> comments while parsing</li> <li><a href=../trailing_commas/ >Trailing Commas</a> - accept trailing commas in arrays and objects</li> <li><a href=../serialization/ >Serialization</a> - pretty-printing, <abbr title="Unicode Transformation Format">UTF</abbr>-8 handling, and number output</li> <li><a href=../no_exceptions/ >Working Without Exceptions</a> - error handling when exceptions are disabled</li> <li><a href=../../home/exceptions/ >Exceptions</a> - list of exceptions and error codes</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="November 4, 2026 16:46:20 UTC">November 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> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../performance/ class="md-footer__link md-footer__link--preLine truncated
|
||||
</code></pre></div> <p>See <a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> for the concept and the trade-offs.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <p>When the input is not valid <abbr title="JavaScript Object Notation">JSON</abbr>, the <code>parse</code> function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or <a href=../../api/basic_json/accept/ ><code>accept</code></a> can be used to only check whether an input is valid <abbr title="JavaScript Object Notation">JSON</abbr>. See <a href=parse_exceptions/ >parsing and exceptions</a> for the available options.</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/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> - deserialize into a document instead of a value</li> <li><a href=../../api/basic_json/accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> - parse newline-delimited <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=large_and_partial_input/ >Large, streamed, and partial input</a> - chunked, concatenated, and very large input</li> <li><a href=parser_callbacks/ >parser callbacks</a> - influence the parsing by a callback function</li> <li><a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - implement a custom <abbr title="Simple API for XML">SAX</abbr> handler</li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - parse into a read-only document and read it through views</li> <li><a href=parse_exceptions/ >parsing and exceptions</a> - control error handling</li> <li><a href=untrusted_input/ >parsing untrusted input</a> - what to consider when parsing input from untrusted sources</li> <li><a href=../../api/operator_gtgt/ ><code>operator>></code></a> - deserialize from stream</li> <li><a href=../../api/json_sax/ ><code>json_sax</code></a> - documentation of the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../api/basic_json/parse_error/ ><code>parse_error</code></a> - exception thrown on a parse error</li> <li><a href=../comments/ >Comments</a> - ignore <code>//</code> and <code>/* */</code> comments while parsing</li> <li><a href=../trailing_commas/ >Trailing Commas</a> - accept trailing commas in arrays and objects</li> <li><a href=../serialization/ >Serialization</a> - pretty-printing, <abbr title="Unicode Transformation Format">UTF</abbr>-8 handling, and number output</li> <li><a href=../no_exceptions/ >Working Without Exceptions</a> - error handling when exceptions are disabled</li> <li><a href=../../home/exceptions/ >Exceptions</a> - list of exceptions and error codes</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="November 7, 2026 09:11:09 UTC">November 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> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../performance/ class="md-footer__link md-footer__link--preLine truncated
|
||||
@@ -54,12 +54,12 @@ When using `operator>>` to read several concatenated values this way, a value th
|
||||
|
||||
All inputs produce the same values and the same exceptions, but they are read in different ways, which makes some of them faster than others:
|
||||
|
||||
| input | how it is read |
|
||||
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory | the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time |
|
||||
| `std::istream` (`std::ifstream`, `std::istringstream`, ...) | the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up |
|
||||
| `FILE*` | one character at a time, with the file locked once for the whole parse |
|
||||
| other iterator ranges (e.g., `std::list<char>`, `std::istreambuf_iterator<char>`), wide strings | one character at a time |
|
||||
| input | how it is read |
|
||||
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory | the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time |
|
||||
| `std::istream` (`std::ifstream`, `std::istringstream`, ...) | the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up |
|
||||
| `FILE*` | with glibc and the Apple C library, the characters the `FILE` holds in its buffer are scanned in bulk like a stream's; elsewhere one character at a time; the file is locked once for the whole parse |
|
||||
| other iterator ranges (e.g., `std::list<char>`, `std::istreambuf_iterator<char>`), wide strings | one character at a time |
|
||||
|
||||
Parsing a file from a `std::ifstream` is therefore only about 10 to 20 % slower than reading the whole file into a `std::string` first and parsing that, and it needs no memory for a copy of the file. The stream is never read ahead: after parsing, it is positioned exactly as if every character had been read one at a time, so [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) can still read several values from one stream (see also [JSON Lines](https://json.nlohmann.me/features/parsing/json_lines/index.md)).
|
||||
|
||||
|
||||
@@ -27,8 +27,8 @@ A `#!cpp std::istream` (including `#!cpp std::ifstream`) gets the same bulk scan
|
||||
characters its stream buffer already holds (the *get area*) and asks the stream buffer for more only when they are used
|
||||
up. Nothing is read ahead, so the stream is left exactly where it would be after reading one character at a time, and
|
||||
[`operator>>`](../api/operator_gtgt.md) can still read several values from one stream. A stream buffer without a get
|
||||
area is read one character at a time. A `#!cpp FILE*` is still read one character at a time, but `file_input_adapter`
|
||||
locks the file once per parse instead of once per character. See
|
||||
area is read one character at a time. A `#!cpp FILE*` is locked once per parse instead of once per character, and with
|
||||
glibc and the Apple C library, the characters in its buffer are scanned in bulk as a stream's get area is. See
|
||||
[input sources and performance](parsing/index.md#input-sources-and-performance) for the full table. According to the
|
||||
description of [#5828](https://github.com/nlohmann/json/pull/5828), parsing from a stream is within about 10 to 20 % of
|
||||
parsing an equivalent `#!cpp std::string`.
|
||||
|
||||
@@ -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=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/performance/" rel="canonical"><link href=../object_order/ rel=prev><link href=../parsing/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>Performance - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.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=custom data-md-color-accent=custom> <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=#performance 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> <img src=../../images/wordmark-header.svg alt=logo> </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> Performance </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=custom data-md-color-accent=custom 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=custom data-md-color-accent=custom 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-1Line 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=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/performance/" rel="canonical"><link href=../object_order/ rel=prev><link href=../parsing/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>Performance - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.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=custom data-md-color-accent=custom> <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=#performance 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> <img src=../../images/wordmark-header.svg alt=logo> </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> Performance </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=custom data-md-color-accent=custom 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=custom data-md-color-accent=custom 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-1Line truncated
|
||||
<span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>f</span><span class=p>(</span><span class=s>"example.json"</span><span class=p>);</span>
|
||||
<span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
|
||||
</code></pre></div> <p>Two macros switch the stream optimizations off without changing any result: <a href=../../api/macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> for stream buffers that do not follow the usual <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>streambuf</span></code> contract, and <a href=../../api/macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a> for programs in which another thread must use the same <code class=highlight><span class=kt>FILE</span></code> object while it is parsed.</p> <p>For contiguous input with many non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters, <a href=../../api/macros/json_use_simdutf/ ><code>JSON_USE_SIMDUTF</code></a> can additionally speed up <abbr title="Unicode Transformation Format">UTF</abbr>-8 validation by using the <a href="https://github.com/simdutf/simdutf">simdutf</a> library instead of the built-in scalar validator; streaming inputs (files, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>, wide strings, user-defined adapters) always use the scalar path regardless of this macro.</p> <h2 id=large-documents>Large documents<a class=headerlink href=#large-documents title="Permanent link">¶</a></h2> <p>Parsing always produces <abbr title="Simple API for XML">SAX</abbr> events internally; <a href=../../api/basic_json/parse/ ><code>parse</code></a> simply feeds them to a consumer that builds a complete <code>basic_json</code> value tree (a <abbr title="Document Object Model">DOM</abbr>) in memory. For documents too large to comfortably hold as a <abbr title="Document Object Model">DOM</abbr>, three alternatives avoid building it:</p> <ul> <li>Implement the <a href=../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> directly and pass it to <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a>; only the parts of the input you choose to keep ever become <code>basic_json</code> values.</li> <li>Pass a <a href=../parsing/parser_callbacks/ >parser callback</a> to <code>parse</code>. This still builds a <abbr title="Document Object Model">DOM</abbr>, but the callback can discard finished elements as soon as they are handled, so memory usage stays bounded by one element (plus the unparsed remainder of the input) instead of the whole document — see the <a href=../parsing/parser_callbacks/#recipe-streaming-a-large-homogeneous-array>recipe for streaming a large homogeneous array</a>.</li> <li>Parse into a <a href=../json_view/ ><code>json_document</code></a> (<code class=highlight><span class=o><</span><span class=n>nlohmann</span><span class=o>/</span><span class=n>json_view</span><span class=p>.</span><span class=n>hpp</span><span class=o>></span></code>) instead of a <code>basic_json</code>. It keeps the input text and builds a flat index of 16 bytes per value; strings and floating-point numbers are not copied, but read from the text when needed. Read-only <a href=../../api/basic_json_view/ >views</a> give the familiar element access, and only the parts you <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a> become <code>basic_json</code> values. A document that borrows the text instead of owning a copy needs the text to outlive it; see <a href=../json_view/#choosing-between-json-ordered_json-the-sax-interface-and-json_view>choosing between <code>json</code>, the <abbr title="Simple API for XML">SAX</abbr> interface, and <code>json_view</code></a>.</li> </ul> <p>If the data is naturally record-oriented, consider <a href=../parsing/json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> instead of one large <abbr title="JavaScript Object Notation">JSON</abbr> document: reading and parsing it line by line with <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>getline</span></code> means only one line's value is ever in memory at a time, and a malformed line does not invalidate lines already processed.</p> <h2 id=binary-formats>Binary formats<a class=headerlink href=#binary-formats title="Permanent link">¶</a></h2> <p><abbr title="JavaScript Object Notation">JSON</abbr> text is not a compact format. If the data is only exchanged between programs (not read by humans), the <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, and <abbr title="Universal Binary JSON">UBJSON</abbr> — encode the same values more compactly, which reduces both the bytes transferred and, for most of them, the work needed to parse them back. The <a href=../binary_formats/#sizes>size comparison</a> on that page, measured against minified <abbr Line truncated
|
||||
@@ -14,4 +14,4 @@
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf>"my_type.hpp"</span>
|
||||
|
||||
<span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=w> </span><span class=nf>my_type::config</span><span class=p>()</span><span class=w> </span><span class=k>const</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>
|
||||
</code></pre></div> <p>One caveat: <abbr title="Application Binary Interface">ABI</abbr>-affecting macros such as <code>JSON_DIAGNOSTICS</code> and <code>JSON_DIAGNOSTIC_POSITIONS</code> are encoded into the library's <a href=../namespace/#limitations>inline namespace name</a>. Every translation unit — whether it includes <code>json_fwd.hpp</code> or the full header — must define them the same way, or linking fails with undefined references instead of a compile error.</p> <p>If I/O support is not needed at all, <a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a> excludes <code><cstdio></code>, <code><ios></code>, <code><iosfwd></code>, <code><istream></code>, and <code><ostream></code> outright and drops the <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>/<code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> <code>parse</code> overloads and <a href=../../api/operator_ltlt/ ><code>operator<<</code></a> that depend on them (<code>dump()</code> itself is unaffected, since it only returns a string); it exists for environments where those headers are unavailable (such as Intel <abbr title="Software Guard Extensions">SGX</abbr>), and as a side effect those headers are then never processed by the compiler at all.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../home/design_goals/ >Design goals</a> - why this library does not optimize for speed first</li> <li><a href=../../home/architecture/ >Architecture</a> - how input adapters, the lexer, and the serializer fit together</li> <li><a href=../parsing/ >Parsing</a> - the available parsing functions and inputs</li> <li><a href=../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - parse without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - parse into a flat index of the text and read it without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../binary_formats/ >Binary formats</a> - compact alternatives to <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../object_order/ >Object Order</a> - <code>json</code> vs. <code>ordered_json</code> and other <code>ObjectType</code> choices</li> <li><a href=../types/template_parameters/ >Template Parameter Requirements</a> - custom container and allocator types</li> <li><a href=../macros/ >Supported macros</a> - overview of all configuration macros, including the diagnostics ones above</li> <li><a href=../../api/macros/json_no_simd/ ><code>JSON_NO_SIMD</code></a> - disable <abbr title="Single Instruction, Multiple Data">SIMD</abbr> acceleration</li> <li><a href=../../api/macros/json_use_simdutf/ ><code>JSON_USE_SIMDUTF</code></a> - use simdutf for <abbr title="Unicode Transformation Format">UTF</abbr>-8 validation</li> <li><a href=../../api/macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> - disable the stream bulk scan</li> <li><a href=../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - parse with a <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../api/json_view/ ><code>json_view</code></a> - a non-owning view of a value in a document</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="November 4, 2026 16:46:20 UTC">November 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"><pathLine truncated
|
||||
</code></pre></div> <p>One caveat: <abbr title="Application Binary Interface">ABI</abbr>-affecting macros such as <code>JSON_DIAGNOSTICS</code> and <code>JSON_DIAGNOSTIC_POSITIONS</code> are encoded into the library's <a href=../namespace/#limitations>inline namespace name</a>. Every translation unit — whether it includes <code>json_fwd.hpp</code> or the full header — must define them the same way, or linking fails with undefined references instead of a compile error.</p> <p>If I/O support is not needed at all, <a href=../../api/macros/json_no_io/ ><code>JSON_NO_IO</code></a> excludes <code><cstdio></code>, <code><ios></code>, <code><iosfwd></code>, <code><istream></code>, and <code><ostream></code> outright and drops the <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>/<code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> <code>parse</code> overloads and <a href=../../api/operator_ltlt/ ><code>operator<<</code></a> that depend on them (<code>dump()</code> itself is unaffected, since it only returns a string); it exists for environments where those headers are unavailable (such as Intel <abbr title="Software Guard Extensions">SGX</abbr>), and as a side effect those headers are then never processed by the compiler at all.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">¶</a></h2> <ul> <li><a href=../../home/design_goals/ >Design goals</a> - why this library does not optimize for speed first</li> <li><a href=../../home/architecture/ >Architecture</a> - how input adapters, the lexer, and the serializer fit together</li> <li><a href=../parsing/ >Parsing</a> - the available parsing functions and inputs</li> <li><a href=../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - parse without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - parse into a flat index of the text and read it without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../binary_formats/ >Binary formats</a> - compact alternatives to <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../object_order/ >Object Order</a> - <code>json</code> vs. <code>ordered_json</code> and other <code>ObjectType</code> choices</li> <li><a href=../types/template_parameters/ >Template Parameter Requirements</a> - custom container and allocator types</li> <li><a href=../macros/ >Supported macros</a> - overview of all configuration macros, including the diagnostics ones above</li> <li><a href=../../api/macros/json_no_simd/ ><code>JSON_NO_SIMD</code></a> - disable <abbr title="Single Instruction, Multiple Data">SIMD</abbr> acceleration</li> <li><a href=../../api/macros/json_use_simdutf/ ><code>JSON_USE_SIMDUTF</code></a> - use simdutf for <abbr title="Unicode Transformation Format">UTF</abbr>-8 validation</li> <li><a href=../../api/macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> - disable the stream bulk scan</li> <li><a href=../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - parse with a <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../api/json_view/ ><code>json_view</code></a> - a non-owning view of a value in a document</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="November 7, 2026 09:11:09 UTC">November 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"><pathLine truncated
|
||||
@@ -13,7 +13,7 @@ For inputs backed by contiguous, single-byte memory — a `std::string`, a `std:
|
||||
- it can reconstruct already-consumed input on demand for error messages, instead of copying every character as it is read, and
|
||||
- the lexer can scan ordinary string characters, numbers, and indentation directly out of the buffer, several bytes at a time, rather than one character (and one function call) at a time.
|
||||
|
||||
A `std::istream` (including `std::ifstream`) gets the same bulk scanning: `input_stream_adapter` scans the characters its stream buffer already holds (the *get area*) and asks the stream buffer for more only when they are used up. Nothing is read ahead, so the stream is left exactly where it would be after reading one character at a time, and [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) can still read several values from one stream. A stream buffer without a get area is read one character at a time. A `FILE*` is still read one character at a time, but `file_input_adapter` locks the file once per parse instead of once per character. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance) for the full table. According to the description of [#5828](https://github.com/nlohmann/json/pull/5828), parsing from a stream is within about 10 to 20 % of parsing an equivalent `std::string`.
|
||||
A `std::istream` (including `std::ifstream`) gets the same bulk scanning: `input_stream_adapter` scans the characters its stream buffer already holds (the *get area*) and asks the stream buffer for more only when they are used up. Nothing is read ahead, so the stream is left exactly where it would be after reading one character at a time, and [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) can still read several values from one stream. A stream buffer without a get area is read one character at a time. A `FILE*` is locked once per parse instead of once per character, and with glibc and the Apple C library, the characters in its buffer are scanned in bulk as a stream's get area is. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance) for the full table. According to the description of [#5828](https://github.com/nlohmann/json/pull/5828), parsing from a stream is within about 10 to 20 % of parsing an equivalent `std::string`.
|
||||
|
||||
Inputs that are still read one character at a time: iterator ranges that are not contiguous (e.g. `std::list<char>` or `std::istreambuf_iterator<char>`), wide strings, and user-defined adapters. An iterator pair over non-contiguous but random-access storage (e.g. `std::deque<char>::iterator`) gets the first optimization but not the second, since the byte-scanning fast path requires contiguous storage.
|
||||
|
||||
|
||||
@@ -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":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, converting your own C++ types, JSON Pointer/Patch/Merge Patch, binary formats, zero-copy views, 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, as well as for <code>json_document</code> and <code>json_view</code>.</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> </p>"},{"location":"api/is_json_view/","title":"nlohmann::is_json_view","text":"<p>Defined in header <code><nlohmann/json_view.hpp></code></p> <pre><code>template<typename T>\nstruct is_json_view;\n</code></pre> <p>A type trait: <code>is_json_view<T>::value</code> is <code>true</code> if <code>T</code> is a <code>basic_json_view</code> of any <code>BasicJsonType</code> and any <code>view_mode</code> -- <code>json_view</code>, <code>json_editable_view</code>, <code>ordered_json_view</code>, ... -- and <code>false</code> otherwise, for <code>basic_json</code> as well.</p> <p>It is meant for constraining templates that accept views, in particular a <code>from_json()</code> that should read views directly: <code>get<T>()</code> on a view calls a <code>from_json()</code> with the view only if that <code>from_json()</code> accepts views but not arbitrary types.</p>"},{"location":"api/is_json_view/#template-parameters","title":"Template parameters","text":"<code>T</code> the type to check (without cv-qualifiers or references)"},{"location":"api/is_json_view/#notes","title":"Notes","text":"<p>A view is recognized by its member type <code>basic_json_type</code> (a <code>basic_json</code> specialization) and its <code>materialize()</code> returning that type, so the trait needs no declaration of the view class.</p>"},{"location":"api/is_json_view/#examples","title":"Examples","text":"Example <p>The example below shows the trait, and a <code>from_json()</code> constrained to <code>json</code> values and views: <code>get<T>()</code> on a view reads the view directly.</p> <pre><code>#include <iostream>\n#include <type_traits>\n#include <nlohmann/json_view.hpp>\n\nusing nlohmann::json;\n\nnamespace ns\n{\nstruct person\n{\n std::string name;\n int age = 0;\n};\n\n// reads json values and views (of any document type), but nothing else\ntemplate < typename J, typename std::enable_if < nlohmann::is_json_view<J>::value || std::is_same<J, json>::value, int >::type = 0 >\nvoid from_json(const J& j, person& p)\n{\n p.name = j.at(\"name\").template get<std::string>();\n p.age = j.at(\"age\").template get<int>();\n}\n} // namespace ns\n\nint main()\n{\n std::cout << std::boolalpha\n << nlohmann::is_json_view<nlohmann::json_view>::value << ' '\n << nlohmann::is_json_view<nlohmann::ordered_json_editable_view>::value << ' '\n << nlohmann::is_json_view<json>::value << '\\n';\n\n const nlohmann::json_document doc = nlohmann::json_document::parse(R\"({\"name\": \"Ada\", \"age\": 36})\");\n const auto p = doc.root().get<ns::person>(); // reads the view, no json value is built\n std::cout << p.name << ' ' << p.age << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>true true false\nAda 36\n</code></pre>"},{"location":"api/is_json_view/#see-also","title":"See also","text":"<ul> <li>basic_json_view - a handle to one value of a document</li> <li>get - which conversions read the view directly</li> <li>view_mode - read-only or editable</li> <li>Writing generic code - functions and <code>from_json()</code> for views</li> </ul>"},{"location":"api/is_json_view/#version-history","title":"Version history","text":"<p>Added in version 3.13.0 unreleased.</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 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":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, converting your own C++ types, JSON Pointer/Patch/Merge Patch, binary formats, zero-copy views, 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, as well as for <code>json_document</code> and <code>json_view</code>.</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> </p>"},{"location":"api/is_json_view/","title":"nlohmann::is_json_view","text":"<p>Defined in header <code><nlohmann/json_view.hpp></code></p> <pre><code>template<typename T>\nstruct is_json_view;\n</code></pre> <p>A type trait: <code>is_json_view<T>::value</code> is <code>true</code> if <code>T</code> is a <code>basic_json_view</code> of any <code>BasicJsonType</code> and any <code>view_mode</code> -- <code>json_view</code>, <code>json_editable_view</code>, <code>ordered_json_view</code>, ... -- and <code>false</code> otherwise, for <code>basic_json</code> as well.</p> <p>It is meant for constraining templates that accept views, in particular a <code>from_json()</code> that should read views directly: <code>get<T>()</code> on a view calls a <code>from_json()</code> with the view only if that <code>from_json()</code> accepts views but not arbitrary types.</p>"},{"location":"api/is_json_view/#template-parameters","title":"Template parameters","text":"<code>T</code> the type to check (without cv-qualifiers or references)"},{"location":"api/is_json_view/#notes","title":"Notes","text":"<p>A view is recognized by its member type <code>basic_json_type</code> (a <code>basic_json</code> specialization) and its <code>materialize()</code> returning that type, so the trait needs no declaration of the view class.</p>"},{"location":"api/is_json_view/#examples","title":"Examples","text":"Example <p>The example below shows the trait, and a <code>from_json()</code> constrained to <code>json</code> values and views: <code>get<T>()</code> on a view reads the view directly.</p> <pre><code>#include <iostream>\n#include <type_traits>\n#include <nlohmann/json_view.hpp>\n\nusing nlohmann::json;\n\nnamespace ns\n{\nstruct person\n{\n std::string name;\n int age = 0;\n};\n\n// reads json values and views (of any document type), but nothing else\ntemplate < typename J, typename std::enable_if < nlohmann::is_json_view<J>::value || std::is_same<J, json>::value, int >::type = 0 >\nvoid from_json(const J& j, person& p)\n{\n p.name = j.at(\"name\").template get<std::string>();\n p.age = j.at(\"age\").template get<int>();\n}\n} // namespace ns\n\nint main()\n{\n std::cout << std::boolalpha\n << nlohmann::is_json_view<nlohmann::json_view>::value << ' '\n << nlohmann::is_json_view<nlohmann::ordered_json_editable_view>::value << ' '\n << nlohmann::is_json_view<json>::value << '\\n';\n\n const nlohmann::json_document doc = nlohmann::json_document::parse(R\"({\"name\": \"Ada\", \"age\": 36})\");\n const auto p = doc.root().get<ns::person>(); // reads the view, no json value is built\n std::cout << p.name << ' ' << p.age << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>true true false\nAda 36\n</code></pre>"},{"location":"api/is_json_view/#see-also","title":"See also","text":"<ul> <li>basic_json_view - a handle to one value of a document</li> <li>get - which conversions read the view directly</li> <li>view_mode - read-only or editable</li> <li>Writing generic code - functions and <code>from_json()</code> for views</li> </ul>"},{"location":"api/is_json_view/#version-history","title":"Version history","text":"<p>Added in version 3.13.0 unreleased.</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 Line truncated
|
||||
+404
-404
File diff suppressed because it is too large.
Load diff
Binary file not shown.
Reference in new issue
Block a user