mirror of
https://github.com/nlohmann/json.git
synced 2026-10-25 23:38:58 +00:00
deploy: cc917d7123
This commit is contained in:
nlohmann committed
1 parent
39c2507b2a
commit
41c601a7d1
57 files changed
+966
-468
No files matched your search
@@ -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> </li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">¶</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></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> </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<std::uint8_t>::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">¶</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">¶</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/ ><code>is_discarded</code></a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">¶</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">¶</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a> in case of an unexpected token, or empty input like a null <code>FILE*</code> or <code>char*</code> pointer, or an <code>std::istream</code> without a stream buffer (<code class=highlight><span class=n>i</span><span class=p>.</span><span class=n>rdbuf</span><span class=p>()</span><span class=w> </span><span class=o>==</span><span class=w> </span><span 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">¶</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<std::uint8_t>::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">¶</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">¶</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><iomanip></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><nlohmann/json.hpp></span>
|
||||
|
||||
@@ -424,4 +424,37 @@
|
||||
"Neptune"
|
||||
]
|
||||
}
|
||||
</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=../accept/ >accept</a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../sax_parse/ >sax_parse</a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ >operator>></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 NUL 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> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>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 NUL 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> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>parse</code> with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>parse</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>parse</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</p> <p>You should be warned by your compiler with a <code>-Wdeprecated-declarations</code> warning if you are using a deprecated function.</p> <p>See the <a href=../../../integration/migration_guide/#parsing>migration guide</a> for how to update existing code.</p> </div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <spanLine truncated
|
||||
</code></pre></div> </details> <details class=example> <summary>Example: parse from <abbr title="Unicode Transformation Format">UTF</abbr>-16, <abbr title="Unicode Transformation Format">UTF</abbr>-32, and wide strings</summary> <p>The encoding is deduced from the character type of the input; <code>std::u16string</code> and <code>std::u32string</code> are interpreted as <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32, and <code>std::wstring</code> uses the platform's <code>wchar_t</code> width. String literals like <code>u"..."</code>, <code>U"..."</code>, and <code>L"..."</code> work as well, as do iterators over wide characters.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf><iostream></span>
|
||||
<span class=cp>#include</span><span class=w> </span><span class=cpf><string></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=c1>// the same JSON text, given in different encodings</span>
|
||||
<span class=w> </span><span class=k>const</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>utf8</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>}"</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>u16string</span><span class=w> </span><span class=n>utf16</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>u</span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>}"</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>u32string</span><span class=w> </span><span class=n>utf32</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>U</span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>}"</span><span class=p>;</span>
|
||||
<span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>wstring</span><span class=w> </span><span class=n>wide</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=sa>L</span><span class=s>"{</span><span class=se>\"</span><span class=s>name</span><span class=se>\"</span><span class=s>:</span><span class=se>\"\u00e9\"</span><span class=s>}"</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// the encoding is deduced from the character type of the input, and all</span>
|
||||
<span class=w> </span><span class=c1>// of them yield the same value</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>utf8</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>utf16</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>utf32</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span>
|
||||
<span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>wide</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// a wide string literal works as well: u"..." is UTF-16, U"..." is UTF-32</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=sa>u</span><span class=s>"[1, 2, 3]"</span><span class=p>)</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
|
||||
<span class=w> </span><span class=c1>// iterators over wide characters work as well</span>
|
||||
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>utf16</span><span class=p>.</span><span class=n>begin</span><span class=p>(),</span><span class=w> </span><span class=n>utf16</span><span class=p>.</span><span class=n>end</span><span class=p>())</span><span class=w> </span><span class=o><<</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
|
||||
<span class=p>}</span>
|
||||
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><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=nt>"name"</span><span class=p>:</span><span class=s2>"é"</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>
|
||||
<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">¶</a></h2> <ul> <li><a href=../accept/ >accept</a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../sax_parse/ >sax_parse</a> - parse input using the <abbr title="Simple API for XML">SAX</abbr> interface</li> <li><a href=../../operator_gtgt/ >operator>></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 NUL 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> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">¶</a></h2> <ul> <li>Added in version 1.0.0.</li> <li>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 NUL 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 release is 3.12.0.">unreleased</span>; before that, some such sequences were accepted or ended the input silently.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>parse</code> with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>parse</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>parse</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span claLine truncated
|
||||
@@ -24,6 +24,8 @@ static basic_json parse(IteratorType first, SentinelType last,
|
||||
|
||||
The `value_type` of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to the iterator type with `operator!=`.
|
||||
|
||||
Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above `U+10FFFF` all yield a [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101).
|
||||
|
||||
## Template parameters
|
||||
|
||||
`InputType` : A compatible input, for instance:
|
||||
@@ -33,9 +35,12 @@ static basic_json parse(IteratorType first, SentinelType last,
|
||||
- a `FILE` pointer (throws if null)
|
||||
- a C-style array of characters
|
||||
- a pointer to a null-terminated string of single byte characters (throws if null)
|
||||
- a `std::string`
|
||||
- a `std::string` or a `std::string_view` (C++17)
|
||||
- a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators
|
||||
(as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
|
||||
- wide characters (`wchar_t`, `char16_t`, `char32_t`), which are converted to UTF-8: a wide string object
|
||||
(`std::wstring`, `std::u16string`, `std::u32string`) or an array (e.g. a wide string literal); a pointer to a
|
||||
null-terminated wide string (e.g. `std::u16string::c_str()`) is not supported
|
||||
```
|
||||
|
||||
`IteratorType` : a compatible iterator type, for instance.
|
||||
@@ -93,6 +98,10 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as [`p
|
||||
|
||||
By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input, rather than as an ordinary (and, outside of a string, invalid) byte; see the [FAQ entry](https://json.nlohmann.me/home/faq/#nul-bytes-in-the-input) for details and the [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) macro to opt into rejecting it instead.
|
||||
|
||||
Parsing into a document instead of a value
|
||||
|
||||
[`basic_json_document::parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) accepts the same inputs and the same options, but keeps the result as a flat index of the parsed values instead of a tree of `basic_json` values. It is faster and uses less memory when only parts of the document are read, and it also accepts a pointer to a null-terminated wide string, which `parse()` does not. See [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md).
|
||||
|
||||
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).
|
||||
@@ -618,6 +627,51 @@ Output:
|
||||
}
|
||||
```
|
||||
|
||||
Example: parse from UTF-16, UTF-32, and wide strings
|
||||
|
||||
The encoding is deduced from the character type of the input; `std::u16string` and `std::u32string` are interpreted as UTF-16 and UTF-32, and `std::wstring` uses the platform's `wchar_t` width. String literals like `u"..."`, `U"..."`, and `L"..."` work as well, as do iterators over wide characters.
|
||||
|
||||
```
|
||||
#include <iostream>
|
||||
#include <string>
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
// the same JSON text, given in different encodings
|
||||
const std::string utf8 = "{\"name\":\"\u00e9\"}";
|
||||
const std::u16string utf16 = u"{\"name\":\"\u00e9\"}";
|
||||
const std::u32string utf32 = U"{\"name\":\"\u00e9\"}";
|
||||
const std::wstring wide = L"{\"name\":\"\u00e9\"}";
|
||||
|
||||
// the encoding is deduced from the character type of the input, and all
|
||||
// of them yield the same value
|
||||
std::cout << json::parse(utf8) << '\n'
|
||||
<< json::parse(utf16) << '\n'
|
||||
<< json::parse(utf32) << '\n'
|
||||
<< json::parse(wide) << '\n';
|
||||
|
||||
// a wide string literal works as well: u"..." is UTF-16, U"..." is UTF-32
|
||||
std::cout << json::parse(u"[1, 2, 3]") << '\n';
|
||||
|
||||
// iterators over wide characters work as well
|
||||
std::cout << json::parse(utf16.begin(), utf16.end()) << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
{"name":"é"}
|
||||
{"name":"é"}
|
||||
{"name":"é"}
|
||||
{"name":"é"}
|
||||
[1,2,3]
|
||||
{"name":"é"}
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [accept](https://json.nlohmann.me/api/basic_json/accept/index.md) - check if the input is valid JSON
|
||||
@@ -640,6 +694,7 @@ Output:
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
Deprecation
|
||||
|
||||
|
||||
Reference in new issue
Block a user