mirror of
https://github.com/nlohmann/json.git
synced 2026-10-20 21:18:15 +00:00
deploy: 4da932f518
This commit is contained in:
1 parent
53e1ee907f
commit
be4d0a6f4b
311 files changed
+1273
-579
No files matched your search
@@ -0,0 +1,34 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/" rel="canonical"><link href=../json_disable_enum_serialization/ rel=prev><link href=../json_disable_tuple_reference_conversion/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>JSON_DISABLE_STREAM_BULK_SCAN - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#json_disable_stream_bulk_scan class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> JSON_DISABLE_STREAM_BULK_SCAN </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.5Line truncated
|
||||
</code></pre></div> <p>When defined to <code>1</code>, parsing from a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> reads the input one character at a time through the stream buffer, as in version 3.12.0 and earlier, instead of scanning the characters that the stream buffer already holds in bulk.</p> <p>The macro is an escape hatch for stream buffers that do not follow the usual contract of <code>std::basic_streambuf</code> (see the requirements on the stream buffer in the notes below). It does not change any result: values, exceptions, and the position of the stream after parsing are the same either way. Only the speed differs.</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>: streams are scanned in bulk.</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_STREAM_BULK_SCAN 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>How streams are scanned</p> <p>A <code>std::streambuf</code> keeps the part of the input it has read but not yet handed out in its <em>get area</em>, the range from <code>gptr()</code> to <code>egptr()</code>. A <code>std::filebuf</code>, for instance, reads the file in blocks of a few kilobytes into its get area, and a <code>std::stringbuf</code> exposes its whole string as one get area.</p> <p>When parsing from a <code>std::istream</code>, the parser scans this get area directly, with the same fast paths that it uses for a <code>std::string</code>: runs of ordinary string characters, numbers, and indentation are recognized several bytes at a time instead of being requested from the stream buffer one character at a time. When the parser reaches the end of the get area, it asks the stream buffer for the next character as before, which makes the stream buffer refill its get area.</p> <p>The parser only reads characters that it would also have read one at a time, and it advances the stream buffer exactly over the characters it consumes. Nothing is read ahead, buffered elsewhere, or put back. Therefore, the stream is left exactly where it was left before:</p> <ul> <li><a href=../../operator_gtgt/ ><code>operator>></code></a> and <a href=../../basic_json/sax_parse/ ><code>sax_parse</code></a> with <code>strict = false</code> can still read several values from one stream, and the stream can still be used with other <code>std::istream</code> functions after a value has been read.</li> <li>With <a href=../json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a>, the stream is still positioned right after a parsed number.</li> <li>Exception messages, including the line, the column, and the last read token, are unchanged.</li> </ul> </div> <div class="admonition note"> <p class=admonition-title>Performance</p> <p>Parsing from a <code>std::ifstream</code> or <code>std::istringstream</code> is typically 1.5 to 2 times as fast as before, and reading many small values from one stream with <code>operator>></code> 1.4 to 4 times as fast. Parsing from a stream is then within about 10 to 20 % of first reading the whole file into a <code>std::string</code> and parsing that.</p> <p>A stream buffer without a get area (one that only overrides <code>underflow()</code> and <code>uflow()</code> and hands out every character from there) offers nothing to scan in bulk, so it is read one character at a time as before.</p> </div> <div class="admonition note"> <p class=admonition-title>Requirements on the stream buffer</p> <p>The bulk scan relies on the following behavior, which every stream buffer of the standard library and every stream buffer that keeps its input in its get area has:</p> <ul> <li>When <code>sgetc()</code> returns a character while <code>gptr() < egptr()</code>, that character is <code>*gptr()</code>; when <code>sbumpc()</code> returns one, it was at <code>gptr()</code> before the call.</li> <li>Characters in the get area are not changed while they are in the get area.</li> <li><code>underflow()</code> or <code>uflow()</code> either sets up a get area that holds the returned character at <code>gptr()</code> (or at <code>gptr() - 1</code> after <code>uflow()</code>), or leaves the get area empty.</li> </ul> <p>A stream buffer that returns characters from <code>uflow()</code> while leaving unrelated characters in its get area, or that changes the characters in its get area in place, does not meet these requirements. Define the macro to <code>1</code> for such stream buffers.</p> </div> <div class="admonition note"> <p class=admonition-title>ABI compatibility</p> <p>The value of this macro is encoded in the <a href=../../../features/namespace/ >namespace</a> (tag <code>_dsbs</code>), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.</p> </div> <div class="admonition note"> <p class=admonition-title>Other inputs</p> <p>Strings, string views, vectors, arrays, and pointer or iterator ranges over contiguous memory are scanned in bulk anyway. Reading from a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> is not affected by this macro; see <a href=../json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</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: reading values from a stream (default)</summary> <p>The stream is scanned in bulk, and the values are read one after the other:</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span clLine truncated
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><sstream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span><span class=w> </span><span class=n>input</span><span class=p>(</span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span><span class=s>{"id": 1} {"id": 2} 42 rest</span><span class=dl>)</span><span class=s>"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j1</span><span class=p>,</span><span class=w> </span><span class=n>j2</span><span class=p>,</span><span class=w> </span><span class=n>j3</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>input</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j1</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j2</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j3</span><span class=p>;</span><span class=w> </span><span class=c1>// {"id":1}, {"id":2}, 42</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>word</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>input</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>word</span><span class=p>;</span><span class=w> </span><span class=c1>// "rest"</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: reading one character at a time (macro defined to 1)</summary> <p>With the macro, the same program reads the stream one character at a time, with the same results:</p> <div class=highlight><pre><span></span><code><span class=cp>#define JSON_DISABLE_STREAM_BULK_SCAN 1</span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><sstream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
|
||||
|
||||
<span class=kt>int</span><span class=w> </span><span class=nf>main</span><span class=p>()</span>
|
||||
<span class=p>{</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span><span class=w> </span><span class=n>input</span><span class=p>(</span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span><span class=s>{"id": 1} {"id": 2} 42 rest</span><span class=dl>)</span><span class=s>"</span><span class=p>);</span>
|
||||
<span class=w> </span><span class=n>json</span><span class=w> </span><span class=n>j1</span><span class=p>,</span><span class=w> </span><span class=n>j2</span><span class=p>,</span><span class=w> </span><span class=n>j3</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>input</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j1</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j2</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>j3</span><span class=p>;</span><span class=w> </span><span class=c1>// {"id":1}, {"id":2}, 42</span>
|
||||
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=w> </span><span class=n>word</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=n>input</span><span class=w> </span><span class=o>>></span><span class=w> </span><span class=n>word</span><span class=p>;</span><span class=w> </span><span class=c1>// "rest"</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/ ><strong>parse</strong></a> - deserialize from a compatible input</li> <li><a href=../../operator_gtgt/ ><strong>operator>></strong></a> - deserialize from stream</li> <li><a href=../../basic_json/sax_parse/ ><strong>sax_parse</strong></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=../json_precise_stream_position/ ><strong>JSON_PRECISE_STREAM_POSITION</strong></a> - leave an input stream positioned right after a parsed number</li> <li><a href=../json_disable_unlocked_file_io/ ><strong>JSON_DISABLE_UNLOCKED_FILE_IO</strong></a> - read a <code>FILE*</code> with the locking stdio functions</li> <li><a href=../../../features/parsing/#input-sources-and-performance>Parsing: input sources and performance</a></li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 19, 2026 20:00:58 UTC">October 19, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Line truncated
|
||||
@@ -0,0 +1,115 @@
|
||||
# JSON_DISABLE_STREAM_BULK_SCAN
|
||||
|
||||
```
|
||||
#define JSON_DISABLE_STREAM_BULK_SCAN /* value */
|
||||
```
|
||||
|
||||
When defined to `1`, parsing from a `std::istream` reads the input one character at a time through the stream buffer, as in version 3.12.0 and earlier, instead of scanning the characters that the stream buffer already holds in bulk.
|
||||
|
||||
The macro is an escape hatch for stream buffers that do not follow the usual contract of `std::basic_streambuf` (see the requirements on the stream buffer in the notes below). It does not change any result: values, exceptions, and the position of the stream after parsing are the same either way. Only the speed differs.
|
||||
|
||||
## Default definition
|
||||
|
||||
The default value is `0`: streams are scanned in bulk.
|
||||
|
||||
```
|
||||
#define JSON_DISABLE_STREAM_BULK_SCAN 0
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
How streams are scanned
|
||||
|
||||
A `std::streambuf` keeps the part of the input it has read but not yet handed out in its *get area*, the range from `gptr()` to `egptr()`. A `std::filebuf`, for instance, reads the file in blocks of a few kilobytes into its get area, and a `std::stringbuf` exposes its whole string as one get area.
|
||||
|
||||
When parsing from a `std::istream`, the parser scans this get area directly, with the same fast paths that it uses for a `std::string`: runs of ordinary string characters, numbers, and indentation are recognized several bytes at a time instead of being requested from the stream buffer one character at a time. When the parser reaches the end of the get area, it asks the stream buffer for the next character as before, which makes the stream buffer refill its get area.
|
||||
|
||||
The parser only reads characters that it would also have read one at a time, and it advances the stream buffer exactly over the characters it consumes. Nothing is read ahead, buffered elsewhere, or put back. Therefore, the stream is left exactly where it was left before:
|
||||
|
||||
- [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) and [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) with `strict = false` can still read several values from one stream, and the stream can still be used with other `std::istream` functions after a value has been read.
|
||||
- With [`JSON_PRECISE_STREAM_POSITION`](https://json.nlohmann.me/api/macros/json_precise_stream_position/index.md), the stream is still positioned right after a parsed number.
|
||||
- Exception messages, including the line, the column, and the last read token, are unchanged.
|
||||
|
||||
Performance
|
||||
|
||||
Parsing from a `std::ifstream` or `std::istringstream` is typically 1.5 to 2 times as fast as before, and reading many small values from one stream with `operator>>` 1.4 to 4 times as fast. Parsing from a stream is then within about 10 to 20 % of first reading the whole file into a `std::string` and parsing that.
|
||||
|
||||
A stream buffer without a get area (one that only overrides `underflow()` and `uflow()` and hands out every character from there) offers nothing to scan in bulk, so it is read one character at a time as before.
|
||||
|
||||
Requirements on the stream buffer
|
||||
|
||||
The bulk scan relies on the following behavior, which every stream buffer of the standard library and every stream buffer that keeps its input in its get area has:
|
||||
|
||||
- When `sgetc()` returns a character while `gptr() < egptr()`, that character is `*gptr()`; when `sbumpc()` returns one, it was at `gptr()` before the call.
|
||||
- Characters in the get area are not changed while they are in the get area.
|
||||
- `underflow()` or `uflow()` either sets up a get area that holds the returned character at `gptr()` (or at `gptr() - 1` after `uflow()`), or leaves the get area empty.
|
||||
|
||||
A stream buffer that returns characters from `uflow()` while leaving unrelated characters in its get area, or that changes the characters in its get area in place, does not meet these requirements. Define the macro to `1` for such stream buffers.
|
||||
|
||||
ABI compatibility
|
||||
|
||||
The value of this macro is encoded in the [namespace](https://json.nlohmann.me/features/namespace/index.md) (tag `_dsbs`), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
|
||||
|
||||
Other inputs
|
||||
|
||||
Strings, string views, vectors, arrays, and pointer or iterator ranges over contiguous memory are scanned in bulk anyway. Reading from a `FILE*` is not affected by this macro; see [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) for that input.
|
||||
|
||||
## Examples
|
||||
|
||||
Example: reading values from a stream (default)
|
||||
|
||||
The stream is scanned in bulk, and the values are read one after the other:
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <sstream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::istringstream input(R"({"id": 1} {"id": 2} 42 rest)");
|
||||
json j1, j2, j3;
|
||||
input >> j1 >> j2 >> j3; // {"id":1}, {"id":2}, 42
|
||||
|
||||
std::string word;
|
||||
input >> word; // "rest"
|
||||
}
|
||||
```
|
||||
|
||||
Example: reading one character at a time (macro defined to 1)
|
||||
|
||||
With the macro, the same program reads the stream one character at a time, with the same results:
|
||||
|
||||
```
|
||||
#define JSON_DISABLE_STREAM_BULK_SCAN 1
|
||||
#include <iostream>
|
||||
#include <sstream>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::istringstream input(R"({"id": 1} {"id": 2} 42 rest)");
|
||||
json j1, j2, j3;
|
||||
input >> j1 >> j2 >> j3; // {"id":1}, {"id":2}, 42
|
||||
|
||||
std::string word;
|
||||
input >> word; // "rest"
|
||||
}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [**parse**](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
|
||||
- [**operator>>**](https://json.nlohmann.me/api/operator_gtgt/index.md) - deserialize from stream
|
||||
- [**sax_parse**](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) - generate SAX events
|
||||
- [**JSON_PRECISE_STREAM_POSITION**](https://json.nlohmann.me/api/macros/json_precise_stream_position/index.md) - leave an input stream positioned right after a parsed number
|
||||
- [**JSON_DISABLE_UNLOCKED_FILE_IO**](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) - read a `FILE*` with the locking stdio functions
|
||||
- [Parsing: input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance)
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0 unreleased.
|
||||
Reference in new issue
Block a user