This commit is contained in:
nlohmann committed 2026-11-12 11:46:38 +00:00
1 parent 8ddeea7128
commit 5097c20962
516 files changed
+7306 -5984

No files matched your search

+3 -3
View File
@@ -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/api/basic_json/parse/" rel="canonical"><link href=../other_error/ rel=prev><link href=../parse_error/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>parse - 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=#nlohmannbasic_jsonparse 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> parse </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 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/api/basic_json/parse/" rel="canonical"><link href=../other_error/ rel=prev><link href=../parse_error/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>parse - 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=#nlohmannbasic_jsonparse 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> parse </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 1Line truncated
<span class=k>template</span><span class=o>&lt;</span><span class=k>typename</span><span class=w> </span><span class=nc>InputType</span><span class=o>&gt;</span>
<span class=k>static</span><span class=w> </span><span class=n>basic_json</span><span class=w> </span><span class=n>parse</span><span class=p>(</span><span class=n>InputType</span><span class=o>&amp;&amp;</span><span class=w> </span><span class=n>i</span><span class=p>,</span>
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>parser_callback_t</span><span class=w> </span><span class=n>cb</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>nullptr</span><span class=p>,</span>
@@ -13,7 +13,7 @@
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>allow_exceptions</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>,</span>
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ignore_comments</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>,</span>
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>ignore_trailing_commas</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>false</span><span class=p>);</span>
</code></pre></div> <ol> <li>Deserialize from a compatible input.</li> <li> <p>Deserialize from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The <code>value_type</code> of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted respectively as <abbr title="Unicode Transformation Format">UTF</abbr>-8, <abbr title="Unicode Transformation Format">UTF</abbr>-16, and <abbr title="Unicode Transformation Format">UTF</abbr>-32. If <code>SentinelType</code> differs from <code>IteratorType</code>, it must be comparable to the iterator type with <code>operator!=</code>.</p> <p>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above <code>U+10FFFF</code> all yield a <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a>.</p> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code>FILE</code> pointer (throws if null)</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters (throws if null)</li> <li>a <code>std::string</code> or a <code>std::string_view</code> (C++17)</li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> <li>wide characters (<code>wchar_t</code>, <code>char16_t</code>, <code>char32_t</code>), which are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8: a wide string object (<code>std::wstring</code>, <code>std::u16string</code>, <code>std::u32string</code>) or an array (e.g. a wide string literal); a pointer to a null-terminated wide string (e.g. <code>std::u16string::c_str()</code>) is not supported</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd> <p>a compatible iterator type, for instance.</p> <ul> <li>a pair of <code>std::string::iterator</code> or <code>std::vector&lt;std::uint8_t&gt;::iterator</code></li> <li>a pair of pointers such as <code>ptr</code> and <code>ptr + len</code></li> </ul> </dd> <dt><code>SentinelType</code></dt> <dd> <p>defaults to <code>IteratorType</code>; may be a different type comparable to <code>IteratorType</code> via <code>operator!=</code>, for instance.</p> <ul> <li>a custom sentinel type for C++20 ranges</li> <li><code>std::default_sentinel_t</code>, when <code>IteratorType</code> is <code>std::counted_iterator</code></li> </ul> </dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>Input to parse from.</dd> <dt><code>cb</code> (in)</dt> <dd>a parser callback function of type <a href=../parser_callback_t/ ><code>parser_callback_t</code></a> which is used to control the deserialization by filtering unwanted values (optional)</dd> <dt><code>allow_exceptions</code> (in)</dt> <dd>whether to throw exceptions in case of a parse error (optional, <code class=highlight><span class=nb>true</span></code> by default)</dd> <dt><code>ignore_comments</code> (in)</dt> <dd>whether comments should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>ignore_trailing_commas</code> (in)</dt> <dd>whether trailing commas in arrays or objects should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of a character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of a character range, or a sentinel value that compares equal to the end iterator with <code>operator!=</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>Deserialized <abbr title="JavaScript Object Notation">JSON</abbr> value; in case of a parse error and <code>allow_exceptions</code> set to <code class=highlight><span class=nb>false</span></code>, the return value will be <code>value_t::discarded</code>. The latter can be checked with <a href=../is_discarded/ ><cLine truncated
</code></pre></div> <ol> <li>Deserialize from a compatible input.</li> <li> <p>Deserialize from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The <code>value_type</code> of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted respectively as <abbr title="Unicode Transformation Format">UTF</abbr>-8, <abbr title="Unicode Transformation Format">UTF</abbr>-16, and <abbr title="Unicode Transformation Format">UTF</abbr>-32. If <code>SentinelType</code> differs from <code>IteratorType</code>, it must be comparable to the iterator type with <code>operator!=</code>.</p> <p>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above <code>U+10FFFF</code> all yield a <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a>.</p> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code>FILE</code> pointer (throws if null)</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters (throws if null)</li> <li>a <code>std::string</code> or a <code>std::string_view</code> (C++17)</li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> <li>wide characters (<code>wchar_t</code>, <code>char16_t</code>, <code>char32_t</code>), which are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8: a wide string object (<code>std::wstring</code>, <code>std::u16string</code>, <code>std::u32string</code>) or an array (e.g. a wide string literal); a pointer to a null-terminated wide string (e.g. <code>std::u16string::c_str()</code>) is not supported</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd> <p>a compatible iterator type, for instance.</p> <ul> <li>a pair of <code>std::string::iterator</code> or <code>std::vector&lt;std::uint8_t&gt;::iterator</code></li> <li>a pair of pointers such as <code>ptr</code> and <code>ptr + len</code></li> </ul> </dd> <dt><code>SentinelType</code></dt> <dd> <p>defaults to <code>IteratorType</code>; may be a different type comparable to <code>IteratorType</code> via <code>operator!=</code>, for instance.</p> <ul> <li>a custom sentinel type for C++20 ranges</li> <li><code>std::default_sentinel_t</code>, when <code>IteratorType</code> is <code>std::counted_iterator</code></li> </ul> </dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>Input to parse from.</dd> <dt><code>cb</code> (in)</dt> <dd>a parser callback function of type <a href=../parser_callback_t/ ><code>parser_callback_t</code></a> which is used to control the deserialization by filtering unwanted values (optional)</dd> <dt><code>allow_exceptions</code> (in)</dt> <dd>whether to throw exceptions in case of a parse error (optional, <code class=highlight><span class=nb>true</span></code> by default)</dd> <dt><code>ignore_comments</code> (in)</dt> <dd>whether comments should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>ignore_trailing_commas</code> (in)</dt> <dd>whether trailing commas in arrays or objects should be ignored and treated like whitespace (<code class=highlight><span class=nb>true</span></code>) or yield a parse error (<code class=highlight><span class=nb>false</span></code>); (optional, <code class=highlight><span class=nb>false</span></code> by default)</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of a character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of a character range, or a sentinel value that compares equal to the end iterator with <code>operator!=</code></dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>Deserialized <abbr title="JavaScript Object Notation">JSON</abbr> value; in case of a parse error and <code>allow_exceptions</code> set to <code class=highlight><span class=nb>false</span></code>, the return value will be <code>value_t::discarded</code>. The latter can be checked with <a href=../is_discarded/ ><cLine truncated
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iomanip&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
@@ -457,4 +457,4 @@
<span class=p>{</span><span class=nt>"name"</span><span class=p>:</span><span class=s2>"é"</span><span class=p>}</span>
<span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>]</span>
<span class=p>{</span><span class=nt>"name"</span><span class=p>:</span><span class=s2>"é"</span><span class=p>}</span>
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../sax_parse/ ><code>sax_parse</code></a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ ><code>operator&gt;&gt;</code></a> - deserialize from stream</li> <li><a href=../../macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> - opt in to rejecting a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input</li> <li><a href=../../macros/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=../../macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a> - read a <code>FILE*</code> with the locking stdio functions</li> <li><a href=../../../features/parsing/ >Parsing</a> - overview of the parsing functions</li> <li><a href=../../../features/comments/ >Comments</a> - ignore <code>//</code> and <code>/* */</code> comments while parsing</li> <li><a href=../../../features/trailing_commas/ >Trailing Commas</a> - accept trailing commas in arrays and objects</li> <li><a href=../../../features/parsing/parser_callbacks/ >Parser Callbacks</a> - filter or inspect values while parsing</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</li> <li><a href=../../../features/parsing/untrusted_input/ >Parsing Untrusted Input</a> - limits and checks for input you do not control</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Overload for contiguous containers (1) added in version 2.0.3.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.0.</li> <li>Changed <a href=../../../features/assertions/ >runtime assertion</a> in case of <code>FILE*</code> null pointers to exception in version 3.12.0.</li> <li>Added <code>ignore_trailing_commas</code> in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>JSON_STRICT_NUL_HANDLING</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to optionally reject a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.</li> <li>Extended empty-input detection to also cover an <code>std::istream</code> without a stream buffer, and fixed a crash (<code>std::terminate</code>) when parsing from an <code>std::istream</code> with <code>eofbit</code> in its exception mask, in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Parsing from an <code>std::istream</code> scans the characters in its stream buffer in bulk 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> (<a href=../../macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> restores reading one character at a time).</li> <li>Parsing from a <code>FILE*</code> locks the file once instead of once per character 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> (<a href=../../macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a> restores <code>std::fgetc</code>).</li> <li>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above <code>U+10FFFF</code>) is rejected with <code>parse_error.101</code> in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest releasLine truncated
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../sax_parse/ ><code>sax_parse</code></a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ ><code>operator&gt;&gt;</code></a> - deserialize from stream</li> <li><a href=../../macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> - opt in to rejecting a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input</li> <li><a href=../../macros/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=../../macros/json_disable_unlocked_file_io/ ><code>JSON_DISABLE_UNLOCKED_FILE_IO</code></a> - read a <code>FILE*</code> with the locking stdio functions</li> <li><a href=../../../features/parsing/ >Parsing</a> - overview of the parsing functions</li> <li><a href=../../../features/comments/ >Comments</a> - ignore <code>//</code> and <code>/* */</code> comments while parsing</li> <li><a href=../../../features/trailing_commas/ >Trailing Commas</a> - accept trailing commas in arrays and objects</li> <li><a href=../../../features/parsing/parser_callbacks/ >Parser Callbacks</a> - filter or inspect values while parsing</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</li> <li><a href=../../../features/parsing/untrusted_input/ >Parsing Untrusted Input</a> - limits and checks for input you do not control</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>Overload for contiguous containers (1) added in version 2.0.3.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.0.</li> <li>Changed <a href=../../../features/assertions/ >runtime assertion</a> in case of <code>FILE*</code> null pointers to exception in version 3.12.0.</li> <li>Added <code>ignore_trailing_commas</code> in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li><code>JSON_STRICT_NUL_HANDLING</code> added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to optionally reject a <abbr title="Null character (U+0000, byte value 0)">NUL</abbr> byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.</li> <li>Extended empty-input detection to also cover an <code>std::istream</code> without a stream buffer, and fixed a crash (<code>std::terminate</code>) when parsing from an <code>std::istream</code> with <code>eofbit</code> in its exception mask, in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>.</li> <li>Fixed the position that a <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a> reports for an unexpected number that is followed by a line feed 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>: for the input <code>1</code>, line feed, <code>2</code>, line feed, version 3.12.0 reported "line 2, column 0" and version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> reports "line 2, column 1"; for <code>1 2</code> and a line feed, the report was "line 1, column 0" and is now "line 1, column 3".</li> <li>Parsing from an <code>std::istream</code> scans the characters in its stream buffer in bulk 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> (<a href=../../macros/json_disable_stream_bulk_scan/ ><code>JSON_DISABLE_STREAM_BULK_SCAN</code></a> restores reading one character at a time).</li> <li>Parsing from a <code>FILE*</code> locks the file once instead of Line truncated
+2 -1
View File
@@ -104,7 +104,7 @@ Parsing into a document instead of a value
Performance
Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A `std::istream` comes close: the parser scans the characters its stream buffer holds in bulk, without reading ahead, so the stream is left exactly where it would be after reading one character at a time. A `FILE*` is read one character at a time, but the file is locked only once, so other threads that use the same `FILE` object wait until parsing is done. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance), [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md), and [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md).
Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A `std::istream` comes close: the parser scans the characters its stream buffer holds in bulk, without reading ahead, so the stream is left exactly where it would be after reading one character at a time. With glibc and the Apple C library, the characters the `FILE` holds in its buffer are scanned in bulk like a stream's; elsewhere a `FILE*` is read one character at a time. Where the C library has unlocked stdio functions, the file is locked only once, so other threads that use the same `FILE` object wait until parsing is done, unless [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) is defined to `1`. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance) and [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md).
## Examples
@@ -698,6 +698,7 @@ Output:
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 unreleased to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.
- Extended empty-input detection to also cover an `std::istream` without a stream buffer, and fixed a crash (`std::terminate`) when parsing from an `std::istream` with `eofbit` in its exception mask, in version 3.13.0 unreleased.
- Fixed the position that a [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101) reports for an unexpected number that is followed by a line feed in version 3.13.0 unreleased: for the input `1`, line feed, `2`, line feed, version 3.12.0 reported "line 2, column 0" and version 3.13.0 unreleased reports "line 2, column 1"; for `1 2` and a line feed, the report was "line 1, column 0" and is now "line 1, column 3".
- Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0 unreleased ([`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md) restores reading one character at a time).
- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0 unreleased ([`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) restores `std::fgetc`).
- Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above `U+10FFFF`) is rejected with `parse_error.101` in version 3.13.0 unreleased; before that, some such sequences were accepted or ended the input silently.