deploy: cc917d7123

2026-10-25 12:04:42 +00:00 · 2026-10-25 05:19:48 +00:00
1 parent 39c2507b2a
commit 41c601a7d1
@@ -6,7 +6,9 @@ JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-
 magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like
 Python. The whole library is available as a single header, `json.hpp`, with no dependencies, no subproject, and no
 complex build system to set up; a companion header, `json_fwd.hpp`, provides forward declarations to keep compile times
-down. See [header-only integration](integration/index.md) for details. It is heavily unit-tested with 100% code
+down, `<nlohmann/json_literals.hpp>` holds the user-defined string literals on their own, and
+`<nlohmann/json_view.hpp>` adds zero-copy views and editable documents. See
+[header-only integration](integration/index.md) for details. It is heavily unit-tested with 100% code
 coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google
 OSS-Fuzz.

@@ -58,7 +60,8 @@ Conda, and more), and pkg-config.

    ---

-    Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.
+    Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, zero-copy views,
+    and more.

    [:octicons-arrow-right-24: Features](features/index.md)

@@ -74,7 +77,8 @@ Conda, and more), and pkg-config.

    ---

-    The complete reference for `basic_json` and its member functions, types, and related classes.
+    The complete reference for `basic_json` and its member functions, types, and related classes, as well as for
+    `json_document` and `json_view`.

    [:octicons-arrow-right-24: API documentation](api/basic_json/index.md)

@@ -44,6 +44,22 @@ are collected in [Template Parameter Requirements](../../features/types/template
 - [**json**](../json.md) - default specialization
 - [**ordered_json**](../ordered_json.md) - a specialization that maintains the insertion order of object keys

+## Documents and views
+
+Besides `basic_json`, the library offers a second way to hold a parsed JSON text: a
+[`basic_json_document`](../basic_json_document/index.md), which owns or borrows the text and holds a flat index of the
+values in it, and a [`basic_json_view`](../basic_json_view/index.md), a read-only handle to one value of such a document.
+Both are defined in the header `<nlohmann/json_view.hpp>`; see
+[Zero-copy JSON views](../../features/json_view.md) for the concept and the trade-offs.
+
+- [**json_document**](../json_document.md) / [**ordered_json_document**](../ordered_json_document.md) - read-only
+  documents of the `basic_json` specialization they belong to
+- [**json_editable_document**](../json_editable_document.md) /
+  [**ordered_json_editable_document**](../ordered_json_editable_document.md) - documents that can be modified in place
+- [**json_view**](../json_view.md) / [**ordered_json_view**](../ordered_json_view.md) - views of a document
+- [**json_editable_view**](../json_editable_view.md) /
+  [**ordered_json_editable_view**](../ordered_json_editable_view.md) - views of an editable document
+
 ## Iterator invalidation

 All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
@@ -409,6 +425,9 @@ Access to the JSON value
 ## See also

 - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
+- [basic_json_document](../basic_json_document/index.md) / [basic_json_view](../basic_json_view/index.md) - parse a JSON
+  text into a flat index and read it through a view
+- [Zero-copy JSON views](../../features/json_view.md) - when to use a document and a view instead of a `basic_json`

 ## Version history

@@ -23,6 +23,9 @@ Checks whether the input is valid JSON.
    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 make this function return `false`.
+
 Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
 (i.e., a parse error) nor creates diagnostic information.

@@ -35,9 +38,12 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
    - a `#!c 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.
@@ -168,6 +174,40 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    
    ```

+??? example "Example: (3) reading from UTF-16 strings"
+
+    The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and
+    `L"..."` work as well.
+
+    ```cpp
+    #include <iostream>
+    #include <string>
+    #include <nlohmann/json.hpp>
+    
+    using json = nlohmann::json;
+    
+    int main()
+    {
+        // a valid JSON text, given as UTF-16
+        const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
+    
+        // an invalid JSON text, given as UTF-16
+        const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
+    
+        std::cout << std::boolalpha
+                  << json::accept(valid_text) << ' '
+                  << json::accept(invalid_text) << '\n';
+    }
+    
+    ```
+
+    Output:
+
+    ```json
+    true false
+    
+    ```
+
 ## See also

 - [parse](parse.md) - deserialize from a compatible input
@@ -194,6 +234,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
+- 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 in version 3.13.0; before that, some such sequences were accepted or
+  ended the input silently.

 !!! warning "Deprecation"

@@ -9,7 +9,7 @@
 <span class=k>static</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>accept</span><span class=p>(</span><span class=n>IteratorType</span><span class=w> </span><span class=n>first</span><span class=p>,</span><span class=w> </span><span class=n>SentinelType</span><span class=w> </span><span class=n>last</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> <p>Checks whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <ol> <li>Reads from a compatible input.</li> <li> <p>Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The value_type of the iterator must be an integral type with a 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> <p>Unlike the <a href=../parse/ ><code>parse()</code></a> function, this function neither throws an exception in case of invalid <abbr title="JavaScript Object Notation">JSON</abbr> input (i.e., a parse error) nor creates diagnostic information.</p> <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 class=highlight><span class=kt>FILE</span></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&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>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 the character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the 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>Whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</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">&para;</a></h2> <p>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a> in case of an empty input like a null <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> or <code class=highlight><span class=kt>char</span><span class=o>*</span></code> pointer.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the length of the input. The parser is a predictive LL(1) parser.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <p>A <abbr title="Unicode Transformation Format">UTF</abbr>-8 byte order mark is silently ignored.</p> <p>By default, a <code>'\0'</code> (NUL) byte anywhere in the input is treated aLine truncated
+</code></pre></div> <p>Checks whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <ol> <li>Reads from a compatible input.</li> <li> <p>Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)</p> <p>The value_type of the iterator must be an integral type with a 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 make this function return <code>false</code>.</p> </li> </ol> <p>Unlike the <a href=../parse/ ><code>parse()</code></a> function, this function neither throws an exception in case of invalid <abbr title="JavaScript Object Notation">JSON</abbr> input (i.e., a parse error) nor creates diagnostic information.</p> <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 class=highlight><span class=kt>FILE</span></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>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 the character range</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the 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>Whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</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=Line 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>

@@ -52,4 +52,23 @@
 <span class=w>              </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>input</span><span class=p>.</span><span class=n>begin</span><span class=p>(),</span><span class=w> </span><span class=n>input</span><span class=p>.</span><span class=n>end</span><span class=p>())</span><span class=w> </span><span class=o>&lt;&lt;</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=kc>true</span><span class=w> </span><span class=kc>false</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../parse/ >parse</a> - deserialize from a compatible input</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&gt;&gt;</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">&para;</a></h2> <ul> <li>Added in version 3.0.0.</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>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>).</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>).</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>accept</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>accept</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>accept</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> <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</sLine truncated
+</code></pre></div> </details> <details class=example> <summary>Example: (3) reading from <abbr title="Unicode Transformation Format">UTF</abbr>-16 strings</summary> <p>The encoding is deduced from the character type of the input. String literals like <code>u"..."</code>, <code>U"..."</code>, and <code>L"..."</code> work as well.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
+<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;string&gt;</span>
+<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</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>// a valid JSON text, given as UTF-16</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>valid_text</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=c1>// an invalid JSON text, given as UTF-16</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>invalid_text</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=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>boolalpha</span>
+<span class=w>              </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>valid_text</span><span class=p>)</span><span class=w> </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=sc>' '</span>
+<span class=w>              </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>accept</span><span class=p>(</span><span class=n>invalid_text</span><span class=p>)</span><span class=w> </span><span class=o>&lt;&lt;</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=kc>true</span><span class=w> </span><span class=kc>false</span>
+</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../parse/ >parse</a> - deserialize from a compatible input</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&gt;&gt;</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">&para;</a></h2> <ul> <li>Added in version 3.0.0.</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>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>).</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>).</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 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>accept</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>accept</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>accept</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> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="Line truncated
@@ -22,6 +22,8 @@ Checks whether the input is valid JSON.

   The value_type of the iterator must be an integral type with a 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 make this function return `false`.
+
 Unlike the [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) function, this function neither throws an exception in case of invalid JSON input (i.e., a parse error) nor creates diagnostic information.

 ## Template parameters
@@ -33,9 +35,12 @@ Unlike the [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) f
 - 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.
@@ -155,6 +160,37 @@ Output:
 true false
 ```

+Example: (3) reading from UTF-16 strings
+
+The encoding is deduced from the character type of the input. String literals like `u"..."`, `U"..."`, and `L"..."` work as well.
+
+```
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a valid JSON text, given as UTF-16
+    const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
+
+    // an invalid JSON text, given as UTF-16
+    const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
+
+    std::cout << std::boolalpha
+              << json::accept(valid_text) << ' '
+              << json::accept(invalid_text) << '\n';
+}
+```
+
+Output:
+
+```
+true false
+```
+
 ## See also

 - [parse](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
@@ -175,6 +211,7 @@ true false
 - `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.
 - 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)).
 - 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)).
+- 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 in version 3.13.0 unreleased; before that, some such sequences were accepted or ended the input silently.

 Deprecation

@@ -1,4 +1,4 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/" rel="canonical"><link href=../../integration/compile_times/ rel=prev><link href=basic_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Overview - 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=#nlohmannbasic_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Overview </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div claLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/" rel="canonical"><link href=../../integration/compile_times/ rel=prev><link href=basic_json/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Overview - 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=#nlohmannbasic_json class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Overview </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div claLine truncated
 <span class=w>    </span><span class=k>template</span><span class=o>&lt;</span><span class=k>typename</span><span class=w> </span><span class=nc>U</span><span class=p>,</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>V</span><span class=p>,</span><span class=w> </span><span class=k>typename</span><span class=p>...</span><span class=w> </span><span class=n>Args</span><span class=o>&gt;</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>ObjectType</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=p>,</span>
 <span class=w>    </span><span class=k>template</span><span class=o>&lt;</span><span class=k>typename</span><span class=w> </span><span class=nc>U</span><span class=p>,</span><span class=w> </span><span class=k>typename</span><span class=p>...</span><span class=w> </span><span class=n>Args</span><span class=o>&gt;</span><span class=w> </span><span class=k>class</span><span class=w> </span><span class=nc>ArrayType</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=p>,</span>
 <span class=w>    </span><span class=k>class</span><span class=w> </span><span class=nc>StringType</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span>
@@ -12,7 +12,7 @@
 <span class=w>    </span><span class=k>class</span><span class=w> </span><span class=nc>CustomBaseClass</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=kt>void</span>
 <span class=o>&gt;</span>
 <span class=k>class</span><span class=w> </span><span class=nc>basic_json</span><span class=p>;</span>
-</code></pre></div> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <table> <thead> <tr> <th>Template parameter</th> <th>Description</th> <th>Derived type</th> </tr> </thead> <tbody> <tr> <td><code>ObjectType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> objects</td> <td><a href=object_t/ ><code>object_t</code></a></td> </tr> <tr> <td><code>ArrayType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> arrays</td> <td><a href=array_t/ ><code>array_t</code></a></td> </tr> <tr> <td><code>StringType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> strings and object keys</td> <td><a href=string_t/ ><code>string_t</code></a></td> </tr> <tr> <td><code>BooleanType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> booleans</td> <td><a href=boolean_t/ ><code>boolean_t</code></a></td> </tr> <tr> <td><code>NumberIntegerType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> integer numbers</td> <td><a href=number_integer_t/ ><code>number_integer_t</code></a></td> </tr> <tr> <td><code>NumberUnsignedType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> unsigned integer numbers</td> <td><a href=number_unsigned_t/ ><code>number_unsigned_t</code></a></td> </tr> <tr> <td><code>NumberFloatType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> floating-point numbers</td> <td><a href=number_float_t/ ><code>number_float_t</code></a></td> </tr> <tr> <td><code>AllocatorType</code></td> <td>type of the allocator to use</td> <td></td> </tr> <tr> <td><code>JSONSerializer</code></td> <td>the serializer to resolve internal calls to <code>to_json()</code> and <code>from_json()</code></td> <td><a href=json_serializer/ ><code>json_serializer</code></a></td> </tr> <tr> <td><code>BinaryType</code></td> <td>type for binary arrays</td> <td><a href=binary_t/ ><code>binary_t</code></a></td> </tr> <tr> <td><code>CustomBaseClass</code></td> <td>extension point for user code</td> <td><a href=json_base_class_t/ ><code>json_base_class_t</code></a></td> </tr> </tbody> </table> <p>The library imposes a number of requirements on these types that are not expressed as C++ concepts, such as the container operations <code>object_t</code> and <code>array_t</code> must provide, or the fact that <code>StringType</code> must be <code>char</code>-based. They are collected in <a href=../../features/types/template_parameters/ >Template Parameter Requirements</a>.</p> <h2 id=specializations>Specializations<a class=headerlink href=#specializations title="Permanent link">&para;</a></h2> <ul> <li><a href=../json/ ><strong>json</strong></a> - default specialization</li> <li><a href=../ordered_json/ ><strong>ordered_json</strong></a> - a specialization that maintains the insertion order of object keys</li> </ul> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">&para;</a></h2> <p>All operations that add values to an <strong>array</strong> (<a href=push_back/ ><code>push_back</code></a> , <a href=operator%2B%3D/ ><code>operator+=</code></a>, <a href=emplace_back/ ><code>emplace_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a href=operator%5B%5D/ ><code>operator[]</code></a> for a non-existing index) can yield a reallocation, in which case all iterators (including the <a href=end/ ><code>end()</code></a> iterator) and all references to the elements are invalidated.</p> <p>For <a href=../ordered_json/ ><code>ordered_json</code></a>, also all operations that add a value to an <strong>object</strong> (<a href=push_back/ ><code>push_back</code></a>, <a href=operator%2B%3D/ ><code>operator+=</code></a>, <a href=emplace/ ><code>emplace</code></a>, <a href=insert/ ><code>insert</code></a>, <a href=update/ ><code>update</code></a>, and <a href=operator%5B%5D/ ><code>operator[]</code></a> for a non-existing key) can yield a reallocation, in which case all iterators (including the <a href=end/ ><code>end()</code></a> iterator) and all references to the elements are invalidated.</p> <h2 id=requirements>Requirements<a class=headerlink href=#requirements title="Permanent link">&para;</a></h2> <p>The class satisfies the following concept requirements:</p> <h3 id=basic>Basic<a class=headerlink href=#basic title="Permanent link">&para;</a></h3> <ul> <li><a href="https://en.cppreference.com/w/cpp/named_req/DefaultConstructible">DefaultConstructible</a>: <abbr title="JavaScript Object Notation">JSON</abbr> values can be default-constructed. The result will be a <abbr title="JavaScript Object Notation">JSON</abbr> null value.</li> <li><a href="https://en.cppreference.com/w/cpp/named_req/MoveConstructible">MoveConstructible</a>: A <abbr title="JavaScript Object Notation">JSON</abbr> value can be constructed from an rvalue arLine truncated
+</code></pre></div> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <table> <thead> <tr> <th>Template parameter</th> <th>Description</th> <th>Derived type</th> </tr> </thead> <tbody> <tr> <td><code>ObjectType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> objects</td> <td><a href=object_t/ ><code>object_t</code></a></td> </tr> <tr> <td><code>ArrayType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> arrays</td> <td><a href=array_t/ ><code>array_t</code></a></td> </tr> <tr> <td><code>StringType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> strings and object keys</td> <td><a href=string_t/ ><code>string_t</code></a></td> </tr> <tr> <td><code>BooleanType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> booleans</td> <td><a href=boolean_t/ ><code>boolean_t</code></a></td> </tr> <tr> <td><code>NumberIntegerType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> integer numbers</td> <td><a href=number_integer_t/ ><code>number_integer_t</code></a></td> </tr> <tr> <td><code>NumberUnsignedType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> unsigned integer numbers</td> <td><a href=number_unsigned_t/ ><code>number_unsigned_t</code></a></td> </tr> <tr> <td><code>NumberFloatType</code></td> <td>type for <abbr title="JavaScript Object Notation">JSON</abbr> floating-point numbers</td> <td><a href=number_float_t/ ><code>number_float_t</code></a></td> </tr> <tr> <td><code>AllocatorType</code></td> <td>type of the allocator to use</td> <td></td> </tr> <tr> <td><code>JSONSerializer</code></td> <td>the serializer to resolve internal calls to <code>to_json()</code> and <code>from_json()</code></td> <td><a href=json_serializer/ ><code>json_serializer</code></a></td> </tr> <tr> <td><code>BinaryType</code></td> <td>type for binary arrays</td> <td><a href=binary_t/ ><code>binary_t</code></a></td> </tr> <tr> <td><code>CustomBaseClass</code></td> <td>extension point for user code</td> <td><a href=json_base_class_t/ ><code>json_base_class_t</code></a></td> </tr> </tbody> </table> <p>The library imposes a number of requirements on these types that are not expressed as C++ concepts, such as the container operations <code>object_t</code> and <code>array_t</code> must provide, or the fact that <code>StringType</code> must be <code>char</code>-based. They are collected in <a href=../../features/types/template_parameters/ >Template Parameter Requirements</a>.</p> <h2 id=specializations>Specializations<a class=headerlink href=#specializations title="Permanent link">&para;</a></h2> <ul> <li><a href=../json/ ><strong>json</strong></a> - default specialization</li> <li><a href=../ordered_json/ ><strong>ordered_json</strong></a> - a specialization that maintains the insertion order of object keys</li> </ul> <h2 id=documents-and-views>Documents and views<a class=headerlink href=#documents-and-views title="Permanent link">&para;</a></h2> <p>Besides <code>basic_json</code>, the library offers a second way to hold a parsed <abbr title="JavaScript Object Notation">JSON</abbr> text: a <a href=../basic_json_document/ ><code>basic_json_document</code></a>, which owns or borrows the text and holds a flat index of the values in it, and a <a href=../basic_json_view/ ><code>basic_json_view</code></a>, a read-only handle to one value of such a document. Both are defined in the header <code>&lt;nlohmann/json_view.hpp&gt;</code>; see <a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> for the concept and the trade-offs.</p> <ul> <li><a href=../json_document/ ><strong>json_document</strong></a> / <a href=../ordered_json_document/ ><strong>ordered_json_document</strong></a> - read-only documents of the <code>basic_json</code> specialization they belong to</li> <li><a href=../json_editable_document/ ><strong>json_editable_document</strong></a> / <a href=../ordered_json_editable_document/ ><strong>ordered_json_editable_document</strong></a> - documents that can be modified in place</li> <li><a href=../json_view/ ><strong>json_view</strong></a> / <a href=../ordered_json_view/ ><strong>ordered_json_view</strong></a> - views of a document</li> <li><a href=../json_editable_view/ ><strong>json_editable_view</strong></a> / <a href=../ordered_json_editable_view/ ><strong>ordered_json_editable_view</strong></a> - views of an editable document</li> </ul> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">&para;</a></h2> <p>All operations that add values to an <strong>array</strong> (<a href=push_back/ ><code>push_back</code></a> , <a href=operator%2B%3D/ ><code>operator+=</code></a>, <a href=emplace_back/ ><code>emplace_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a hrefLine 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>

@@ -78,4 +78,4 @@
 <span class=w>    </span><span class=nt>"pi"</span><span class=p>:</span><span class=w> </span><span class=mf>3.141</span><span class=p>,</span>
 <span class=w>    </span><span class=nt>"size"</span><span class=p>:</span><span class=w> </span><span class=mi>8</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="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259: The JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format</a></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> </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 14, 2026 15:40:55 UTC">October 14, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free Line 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="https://tools.ietf.org/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259: The JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format</a></li> <li><a href=../basic_json_document/ >basic_json_document</a> / <a href=../basic_json_view/ >basic_json_view</a> - parse a <abbr title="JavaScript Object Notation">JSON</abbr> text into a flat index and read it through a view</li> <li><a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - when to use a document and a view instead of a <code>basic_json</code></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> </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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 3Line truncated
@@ -42,6 +42,15 @@ The library imposes a number of requirements on these types that are not express
 - [**json**](https://json.nlohmann.me/api/json/index.md) - default specialization
 - [**ordered_json**](https://json.nlohmann.me/api/ordered_json/index.md) - a specialization that maintains the insertion order of object keys

+## Documents and views
+
+Besides `basic_json`, the library offers a second way to hold a parsed JSON text: a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md), which owns or borrows the text and holds a flat index of the values in it, and a [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md), a read-only handle to one value of such a document. Both are defined in the header `<nlohmann/json_view.hpp>`; see [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) for the concept and the trade-offs.
+
+- [**json_document**](https://json.nlohmann.me/api/json_document/index.md) / [**ordered_json_document**](https://json.nlohmann.me/api/ordered_json_document/index.md) - read-only documents of the `basic_json` specialization they belong to
+- [**json_editable_document**](https://json.nlohmann.me/api/json_editable_document/index.md) / [**ordered_json_editable_document**](https://json.nlohmann.me/api/ordered_json_editable_document/index.md) - documents that can be modified in place
+- [**json_view**](https://json.nlohmann.me/api/json_view/index.md) / [**ordered_json_view**](https://json.nlohmann.me/api/ordered_json_view/index.md) - views of a document
+- [**json_editable_view**](https://json.nlohmann.me/api/json_editable_view/index.md) / [**ordered_json_editable_view**](https://json.nlohmann.me/api/ordered_json_editable_view/index.md) - views of an editable document
+
 ## Iterator invalidation

 All operations that add values to an **array** ([`push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) , [`operator+=`](https://json.nlohmann.me/api/basic_json/operator%2B%3D/index.md), [`emplace_back`](https://json.nlohmann.me/api/basic_json/emplace_back/index.md), [`insert`](https://json.nlohmann.me/api/basic_json/insert/index.md), and [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) for a non-existing index) can yield a reallocation, in which case all iterators (including the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator) and all references to the elements are invalidated.
@@ -384,6 +393,8 @@ Output:
 ## See also

 - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
+- [basic_json_document](https://json.nlohmann.me/api/basic_json_document/index.md) / [basic_json_view](https://json.nlohmann.me/api/basic_json_view/index.md) - parse a JSON text into a flat index and read it through a view
+- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - when to use a document and a view instead of a `basic_json`

 ## Version history

@@ -25,6 +25,10 @@ static basic_json parse(IteratorType first, SentinelType last,
    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`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 ## Template parameters

 `InputType`
@@ -34,9 +38,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.
@@ -112,6 +119,13 @@ By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input
 outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-bytes-in-the-input) for details and the
 [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) macro to opt into rejecting it instead.

+!!! tip "Parsing into a document instead of a value"
+
+    [`basic_json_document::parse`](../basic_json_document/parse.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](../../features/json_view.md).
+
 !!! tip "Performance"

    Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A
@@ -665,6 +679,55 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
    
    ```

+??? example "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.
+
+    ```cpp
+    #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:
+
+    ```json
+    {"name":"é"}
+    {"name":"é"}
+    {"name":"é"}
+    {"name":"é"}
+    [1,2,3]
+    {"name":"é"}
+    
+    ```
+
 ## See also

 - [accept](accept.md) - check if the input is valid JSON
@@ -695,6 +758,9 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
  time).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.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; before that, some such
+  sequences were accepted or ended the input silently.

 !!! warning "Deprecation"

@@ -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">&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></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&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/ ><code>is_discarded</code></a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</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">&para;</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">&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>

@@ -424,4 +424,37 @@
    "Neptune"
  ]
 }
-</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/ >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&gt;&gt;</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">&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 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>&lt;iostream&gt;</span>
+<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;string&gt;</span>
+<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</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>&lt;&lt;</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>&lt;&lt;</span><span class=w> </span><span class=sc>'\n'</span>
+<span class=w>              </span><span class=o>&lt;&lt;</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>&lt;&lt;</span><span class=w> </span><span class=sc>'\n'</span>
+<span class=w>              </span><span class=o>&lt;&lt;</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>&lt;&lt;</span><span class=w> </span><span class=sc>'\n'</span>
+<span class=w>              </span><span class=o>&lt;&lt;</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>&lt;&lt;</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>&lt;&lt;</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>&lt;&lt;</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>&lt;&lt;</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>&lt;&lt;</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">&para;</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&gt;&gt;</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">&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 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

@@ -31,6 +31,10 @@ Read from input and generate SAX events
    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`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).

 ## Template parameters
@@ -42,8 +46,12 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
    - a `FILE` pointer
    - a C-style array of characters
    - a pointer to a null-terminated string of single byte characters
+    - 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 overload (2); a pair of character iterators whose `value_type` is an integral type
@@ -328,6 +336,9 @@ use the same file with stdio functions, but it must not wait for another thread
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
 - Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
+- 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; before that, some such
+  sequences were accepted or ended the input silently.

 !!! warning "Deprecation"

@@ -17,7 +17,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>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>
 <span class=w>                      </span><span class=k>const</span><span class=w> </span><span class=n>cbor_tag_handler_t</span><span class=w> </span><span class=n>tag_handler</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>cbor_tag_handler_t</span><span class=o>::</span><span class=n>error</span><span class=p>);</span>
-</code></pre></div> <p>Read from input and generate <abbr title="Simple API for XML">SAX</abbr> events</p> <ol> <li>Read from a compatible input.</li> <li> <p>Read from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support).</p> <p>The value_type of the iterator must be an integral type with a 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> <p>The <abbr title="Simple API for XML">SAX</abbr> event lister must follow the interface of <a href=../../json_sax/ ><code>json_sax</code></a>.</p> <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</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters</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>a compatible iterator type for overload (2); a pair of character iterators whose <code>value_type</code> is an integral type with a size of 1, 2, or 4 bytes (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)</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 overload (2), 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> <dt><code>SAX</code></dt> <dd>a class fulfilling the <abbr title="Simple API for XML">SAX</abbr> event listener interface; see <a href=../../json_sax/ ><code>json_sax</code></a></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>sax</code> (in)</dt> <dd><abbr title="Simple API for XML">SAX</abbr> event listener (must not be null)</dd> <dt><code>format</code> (in)</dt> <dd>the format to parse (<abbr title="JavaScript Object Notation">JSON</abbr>, <abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, or <abbr title="Universal Binary JSON">UBJSON</abbr>) (optional, <code>input_format_t::json</code> by default), see <a href=../input_format_t/ ><code>input_format_t</code></a> for more information</dd> <dt><code>strict</code> (in)</dt> <dd>whether the input has to be consumed completely (optional, <code class=highlight><span class=nb>true</span></code> by default); when <code class=highlight><span class=nb>false</span></code> and the input is a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>, the character that terminates a number is consumed unless <a href=../../macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code>; see <a href=../../operator_gtgt/#notes><code>operator&gt;&gt;</code></a></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>tag_handler</code> (in)</dt> <dd>how to handle <abbr title="Concise Binary Object Representation">CBOR</abbr> tags; see <a href=../cbor_tag_handler_t/ ><code>cbor_tag_handler_t</code></a>. Ignored for formats other than <abbr title="Concise Line truncated
+</code></pre></div> <p>Read from input and generate <abbr title="Simple API for XML">SAX</abbr> events</p> <ol> <li>Read from a compatible input.</li> <li> <p>Read from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support).</p> <p>The value_type of the iterator must be an integral type with a 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> <p>The <abbr title="Simple API for XML">SAX</abbr> event lister must follow the interface of <a href=../../json_sax/ ><code>json_sax</code></a>.</p> <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</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters</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>a compatible iterator type for overload (2); a pair of character iterators whose <code>value_type</code> is an integral type with a size of 1, 2, or 4 bytes (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)</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 overload (2), 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> <dt><code>SAX</code></dt> <dd>a class fulfilling the <abbr title="Simple API for XML">SAX</abbr> event listener interface; see <a href=../../json_sax/ ><code>json_sax</code></a></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>sax</code> (in)</dt> <dd><abbr title="Simple API for XML">SAX</abbr> event listener (must not be null)</dd> <dt><code>format</code> (in)</dt> <dd>the format to parse (<abbr title="JavaScript Object Notation">JSON</abbr>, <abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, or <abbr title="Universal Binary JSON">UBJSON</abbr>) (optional, <code>input_format_t::json</code> by default), see <a href=../input_format_t/ ><code>input_format_t</code></a> for more information</dd> <dt><code>strict</code> (in)</dt> <dd>whether the input has to be consumed completely (optional, <code class=highlight><span class=nb>true</span></code> by default); when <code class=highlight><span class=nb>false</span></code> and the input is a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>, the character that terminates a number is consumed unless <a href=../../macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code>; see <a href=../../operator_gtgt/#notes><code>operator&gt;&gt;</code></a></dd> <dt><code>ignore_comments</code> (in)</dt> <dd>whether coLine 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;sstream&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
@@ -185,4 +185,4 @@
 <span class=w>            </span><span class=err>ex=</span><span class=p>[</span><span class=err>jso</span><span class=kc>n</span><span class=err>.excep</span><span class=kc>t</span><span class=err>io</span><span class=kc>n</span><span class=err>.parse_error.</span><span class=mi>101</span><span class=p>]</span><span class=w> </span><span class=err>parse</span><span class=w> </span><span class=err>error</span><span class=w> </span><span class=err>a</span><span class=kc>t</span><span class=w> </span><span class=err>li</span><span class=kc>ne</span><span class=w> </span><span class=mi>17</span><span class=p>,</span><span class=w> </span><span class=err>colum</span><span class=kc>n</span><span class=w> </span><span class=mi>6</span><span class=p>:</span><span class=w> </span><span class=err>sy</span><span class=kc>nta</span><span class=err>x</span><span class=w> </span><span class=err>error</span><span class=w> </span><span class=err>while</span><span class=w> </span><span class=err>parsi</span><span class=kc>n</span><span class=err>g</span><span class=w> </span><span class=err>value</span><span class=w> </span><span class=mi>-</span><span class=w> </span><span class=err>u</span><span class=kc>ne</span><span class=err>xpec</span><span class=kc>te</span><span class=err>d</span><span class=w> </span><span class=err>'</span><span class=p>]</span><span class=err>';</span><span class=w> </span><span class=err>expec</span><span class=kc>te</span><span class=err>d</span><span class=w> </span><span class=err>e</span><span class=kc>n</span><span class=err>d</span><span class=w> </span><span class=err>o</span><span class=kc>f</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>pu</span><span class=kc>t</span><span class=err>)</span>

 <span class=err>resul</span><span class=kc>t</span><span class=p>:</span><span class=w> </span><span class=kc>false</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../parse/ >parse</a> - deserialize from a compatible input</li> <li><a href=../accept/ >accept</a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></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">&para;</a></h2> <ul> <li>Added in version 3.2.0.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.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>Added <code>tag_handler</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_PRECISE_STREAM_POSITION</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 leave a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> positioned right after the parsed value when <code>strict</code> is <code class=highlight><span class=nb>false</span></code>.</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>).</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>).</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <p>Overload (2) replaces calls to <code>sax_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>sax_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></code> with <code class=highlight><span class=n>sax_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></code>.</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> <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.Line 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=../parse/ >parse</a> - deserialize from a compatible input</li> <li><a href=../accept/ >accept</a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></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">&para;</a></h2> <ul> <li>Added in version 3.2.0.</li> <li>Ignoring comments via <code>ignore_comments</code> added in version 3.9.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>Added <code>tag_handler</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_PRECISE_STREAM_POSITION</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 leave a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> positioned right after the parsed value when <code>strict</code> is <code class=highlight><span class=nb>false</span></code>.</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>).</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>).</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>sax_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>sax_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></code> with <code class=highlight><span class=n>sax_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></code>.</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> <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 7Line truncated
@@ -30,6 +30,8 @@ Read from input and generate SAX events

   The value_type of the iterator must be an integral type with a 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).
+
 The SAX event lister must follow the interface of [`json_sax`](https://json.nlohmann.me/api/json_sax/index.md).

 ## Template parameters
@@ -41,8 +43,12 @@ The SAX event lister must follow the interface of [`json_sax`](https://json.nloh
 - a `FILE` pointer
 - a C-style array of characters
 - a pointer to a null-terminated string of single byte characters
+- 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 overload (2); a pair of character iterators whose `value_type` is an integral type with a size of 1, 2, or 4 bytes (interpreted respectively as UTF-8, UTF-16, and UTF-32)
@@ -298,6 +304,7 @@ result: false
 - `JSON_PRECISE_STREAM_POSITION` added in version 3.13.0 unreleased to optionally leave a `std::istream` positioned right after the parsed value when `strict` is `false`.
 - 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)).
 - 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)).
+- 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

@@ -9,8 +9,8 @@ class basic_json_document;

 A parsed JSON text, held as a flat index of its values
 ([16 bytes per value](../../home/architecture.md#node-index-of-json-views)) instead of a tree of `BasicJsonType` values.
-Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by
-the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
+Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that
+contain escapes are decoded into one buffer owned by the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
 `basic_json_document`; [`materialize()`](../basic_json_view/materialize.md) turns a subtree into the
 `BasicJsonType` value that [`BasicJsonType::parse()`](../basic_json/parse.md) would have produced for it.

@@ -1,3 +1,3 @@
 <!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json_document/" rel="canonical"><link href=../basic_json/with_t/ rel=prev><link href=basic_json_document/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Overview - 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=#nlohmannbasic_json_document 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> Overview </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> <Line truncated
 <span class=k>class</span><span class=w> </span><span class=nc>basic_json_document</span><span class=p>;</span>
-</code></pre></div> <p>A parsed <abbr title="JavaScript Object Notation">JSON</abbr> text, held as a flat index of its values (<a href=../../home/architecture/#node-index-of-json-views>16 bytes per value</a>) instead of a tree of <code>BasicJsonType</code> values. Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by the document. <a href=../basic_json_view/ ><code>basic_json_view</code></a> is a read-only handle to one value of a <code>basic_json_document</code>; <a href=../basic_json_view/materialize/ ><code>materialize()</code></a> turns a subtree into the <code>BasicJsonType</code> value that <a href=../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> would have produced for it.</p> <p>A document may <strong>borrow</strong> the text it was parsed from (the caller's buffer must then outlive the document) or <strong>own</strong> it (a copy, or an rvalue <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> that was moved in); see <a href=owns_source/ ><code>owns_source</code></a>. <code>basic_json_document</code> is move-only: a copy would duplicate the whole index, the decoded-string buffer, and the owned text, and a move is enough in every use we know of. The index, the decoded strings, and the owned text live in one heap block that the document holds through a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>unique_ptr</span></code>; this is also why views survive a move of the document.</p> <p>With <code class=highlight><span class=n>Editable</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>true</span></code>, the document also offers <a href=set/ ><code>set</code></a>, <a href=push_back/ ><code>push_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a href=erase/ ><code>erase</code></a> to change values in place, see <a href=#edits>Edits</a> below. The source text itself is never written; a read-only document (<code class=highlight><span class=n>Editable</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>false</span></code>, the default) does not carry any of the bookkeeping edits need, and calling any of them on one fails to compile (<code class=highlight><span class=k>static_assert</span></code>).</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>BasicJsonType</code></dt> <dd>a specialization of <a href=../basic_json/ ><code>basic_json</code></a>, for instance <a href=../json/ ><code>json</code></a> or <a href=../ordered_json/ ><code>ordered_json</code></a>. Only 64-bit <code>number_integer_t</code>/<code>number_unsigned_t</code> types are supported; this is checked with a <code>static_assert</code>.</dd> <dt><code>Editable</code></dt> <dd>whether the document supports <a href=set/ ><code>set</code></a>, <a href=push_back/ ><code>push_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a href=erase/ ><code>erase</code></a> (optional, <code class=highlight><span class=nb>false</span></code> by default). See <a href=#edits>Edits</a> below.</dd> </dl> <h2 id=specializations>Specializations<a class=headerlink href=#specializations title="Permanent link">&para;</a></h2> <ul> <li><a href=../json_document/ ><strong>json_document</strong></a> - read-only documents of the default specialization <a href=../json/ ><code>json</code></a></li> <li><a href=../ordered_json_document/ ><strong>ordered_json_document</strong></a> - read-only documents of <a href=../ordered_json/ ><code>ordered_json</code></a></li> <li><a href=../json_editable_document/ ><strong>json_editable_document</strong></a> - editable documents of <a href=../json/ ><code>json</code></a></li> <li><a href=../ordered_json_editable_document/ ><strong>ordered_json_editable_document</strong></a> - editable documents of <a href=../ordered_json/ ><code>ordered_json</code></a></li> </ul> <h2 id=member-types>Member types<a class=headerlink href=#member-types title="Permanent link">&para;</a></h2> <ul> <li><strong>view_type</strong> - the type of view returned by <a href=root/ ><code>root()</code></a> (<code class=highlight><span class=n>basic_json_view</span><span class=o>&lt;</span><span class=n>BasicJsonType</span><span class=p>,</span><span class=w> </span><span class=n>Editable</span><span class=o>&gt;</span></code>)</li> <li><strong>value_t</strong> - the <abbr title="JavaScript Object Notation">JSON</abbr> type enumeration, see <a href=../basic_json/value_t/ ><code>basic_json::value_t</code></a></li> <li><strong>image_check</strong> - how <a href=load/ ><code>load()</code></a> validates an image (<code>full</code>, <code>bounds</code>, <code>none</code>), see <a href=load/#image_check><code>image_check</code></a></li> </ul> <h2 id=member-functions>Member functions<a class=headerlink href=#member-fLine truncated
+</code></pre></div> <p>A parsed <abbr title="JavaScript Object Notation">JSON</abbr> text, held as a flat index of its values (<a href=../../home/architecture/#node-index-of-json-views>16 bytes per value</a>) instead of a tree of <code>BasicJsonType</code> values. Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that contain escapes are decoded into one buffer owned by the document. <a href=../basic_json_view/ ><code>basic_json_view</code></a> is a read-only handle to one value of a <code>basic_json_document</code>; <a href=../basic_json_view/materialize/ ><code>materialize()</code></a> turns a subtree into the <code>BasicJsonType</code> value that <a href=../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> would have produced for it.</p> <p>A document may <strong>borrow</strong> the text it was parsed from (the caller's buffer must then outlive the document) or <strong>own</strong> it (a copy, or an rvalue <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> that was moved in); see <a href=owns_source/ ><code>owns_source</code></a>. <code>basic_json_document</code> is move-only: a copy would duplicate the whole index, the decoded-string buffer, and the owned text, and a move is enough in every use we know of. The index, the decoded strings, and the owned text live in one heap block that the document holds through a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>unique_ptr</span></code>; this is also why views survive a move of the document.</p> <p>With <code class=highlight><span class=n>Editable</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>true</span></code>, the document also offers <a href=set/ ><code>set</code></a>, <a href=push_back/ ><code>push_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a href=erase/ ><code>erase</code></a> to change values in place, see <a href=#edits>Edits</a> below. The source text itself is never written; a read-only document (<code class=highlight><span class=n>Editable</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>false</span></code>, the default) does not carry any of the bookkeeping edits need, and calling any of them on one fails to compile (<code class=highlight><span class=k>static_assert</span></code>).</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>BasicJsonType</code></dt> <dd>a specialization of <a href=../basic_json/ ><code>basic_json</code></a>, for instance <a href=../json/ ><code>json</code></a> or <a href=../ordered_json/ ><code>ordered_json</code></a>. Only 64-bit <code>number_integer_t</code>/<code>number_unsigned_t</code> types are supported; this is checked with a <code>static_assert</code>.</dd> <dt><code>Editable</code></dt> <dd>whether the document supports <a href=set/ ><code>set</code></a>, <a href=push_back/ ><code>push_back</code></a>, <a href=insert/ ><code>insert</code></a>, and <a href=erase/ ><code>erase</code></a> (optional, <code class=highlight><span class=nb>false</span></code> by default). See <a href=#edits>Edits</a> below.</dd> </dl> <h2 id=specializations>Specializations<a class=headerlink href=#specializations title="Permanent link">&para;</a></h2> <ul> <li><a href=../json_document/ ><strong>json_document</strong></a> - read-only documents of the default specialization <a href=../json/ ><code>json</code></a></li> <li><a href=../ordered_json_document/ ><strong>ordered_json_document</strong></a> - read-only documents of <a href=../ordered_json/ ><code>ordered_json</code></a></li> <li><a href=../json_editable_document/ ><strong>json_editable_document</strong></a> - editable documents of <a href=../json/ ><code>json</code></a></li> <li><a href=../ordered_json_editable_document/ ><strong>ordered_json_editable_document</strong></a> - editable documents of <a href=../ordered_json/ ><code>ordered_json</code></a></li> </ul> <h2 id=member-types>Member types<a class=headerlink href=#member-types title="Permanent link">&para;</a></h2> <ul> <li><strong>view_type</strong> - the type of view returned by <a href=root/ ><code>root()</code></a> (<code class=highlight><span class=n>basic_json_view</span><span class=o>&lt;</span><span class=n>BasicJsonType</span><span class=p>,</span><span class=w> </span><span class=n>Editable</span><span class=o>&gt;</span></code>)</li> <li><strong>value_t</strong> - the <abbr title="JavaScript Object Notation">JSON</abbr> type enumeration, see <a href=../basic_json/value_t/ ><code>basic_json::value_t</code></a></li> <li><strong>image_check</strong> - how <a href=load/ ><code>load()</code></a> validates an image (<code>full</code>, <code>bounds</code>, <code>none</code>), see <a href=load/#image_check><code>image_check</code></a></li> </ul> <h2 id=member-functionsLine truncated
@@ -7,7 +7,7 @@ template<typename BasicJsonType, bool Editable = false>
 class basic_json_document;
 ```

-A parsed JSON text, held as a flat index of its values ([16 bytes per value](https://json.nlohmann.me/home/architecture/#node-index-of-json-views)) instead of a tree of `BasicJsonType` values. Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer owned by the document. [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) is a read-only handle to one value of a `basic_json_document`; [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) turns a subtree into the `BasicJsonType` value that [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would have produced for it.
+A parsed JSON text, held as a flat index of its values ([16 bytes per value](https://json.nlohmann.me/home/architecture/#node-index-of-json-views)) instead of a tree of `BasicJsonType` values. Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that contain escapes are decoded into one buffer owned by the document. [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) is a read-only handle to one value of a `basic_json_document`; [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) turns a subtree into the `BasicJsonType` value that [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would have produced for it.

 A document may **borrow** the text it was parsed from (the caller's buffer must then outlive the document) or **own** it (a copy, or an rvalue `std::string` that was moved in); see [`owns_source`](https://json.nlohmann.me/api/basic_json_document/owns_source/index.md). `basic_json_document` is move-only: a copy would duplicate the whole index, the decoded-string buffer, and the owned text, and a move is enough in every use we know of. The index, the decoded strings, and the owned text live in one heap block that the document holds through a `std::unique_ptr`; this is also why views survive a move of the document.

@@ -21,17 +21,19 @@ static basic_json_document parse(IteratorType first, IteratorType last,

 Both overloads accept the same JSON text as [`BasicJsonType::parse()`](../basic_json/parse.md), with the same
 `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (a flat index into
-the input) instead of a tree of `BasicJsonType` values. They take the same inputs as `BasicJsonType::parse()`. Byte
-inputs that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, non-contiguous
-iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](parse_copy.md) to get an
-owned copy of a borrowable input as well.
+the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in
+addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of
+single-byte characters that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, which
+must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the
+Notes. Use [`parse_copy()`](parse_copy.md) to get an owned copy of a borrowable input
+as well.

 ## Template parameters

 `InputType`
 :   A compatible input, for instance:

-    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of single-byte characters
+    - a `#!cpp std::string`, a `#!cpp std::string_view` (C++17), or a C-style array of single-byte characters
    - a pointer to a null-terminated string of single-byte characters (`#!cpp char`, `#!cpp signed char`,
      `#!cpp unsigned char`, `#!cpp std::uint8_t`)
    - a container for which `#!cpp obj.data()` and `#!cpp obj.size()` give contiguous single-byte access, e.g.
@@ -47,6 +49,10 @@ owned copy of a borrowable input as well.
    `#!cpp std::string::iterator`; the iterators of single-byte characters are borrowed or read like the byte inputs
    above, those of wide characters are converted to UTF-8

+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`](../../home/exceptions.md#jsonexceptionparse_error101).
+
 ## Parameters

 `input` (in)
@@ -215,3 +221,5 @@ buffer of a given length, pass a pair of pointers: `#!cpp parse(ptr, ptr + len)`
 ## Version history

 - Added in version 3.13.0.
+- 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`.
@@ -11,7 +11,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, borrowing or owning it depending on its value category and type (see Notes).</li> <li>Deserialize from a pair of input iterators.</li> </ol> <p>Both overloads accept the same <abbr title="JavaScript Object Notation">JSON</abbr> text as <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a>, with the same <code>ignore_comments</code>/<code>ignore_trailing_commas</code> options, but build a <a href=../ ><code>basic_json_document</code></a> (a flat index into the input) instead of a tree of <code>BasicJsonType</code> values. They take the same inputs as <code>BasicJsonType::parse()</code>. Byte inputs that stay alive can be borrowed; all others (streams, <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code>, wide characters, non-contiguous iterators) are read into a copy that the document owns -- see the Notes. Use <a href=../parse_copy/ ><code>parse_copy()</code></a> to get an owned copy of a borrowable input as well.</p> <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>a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string_view</span></code>, or a C-style array of single-byte characters</li> <li>a pointer to a null-terminated string of single-byte characters (<code class=highlight><span class=kt>char</span></code>, <code class=highlight><span class=kt>signed</span><span class=w> </span><span class=kt>char</span></code>, <code class=highlight><span class=kt>unsigned</span><span class=w> </span><span class=kt>char</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span></code>)</li> <li>a container for which <code class=highlight><span class=n>obj</span><span class=p>.</span><span class=n>data</span><span class=p>()</span></code> and <code class=highlight><span class=n>obj</span><span class=p>.</span><span class=n>size</span><span class=p>()</span></code> give contiguous single-byte access, e.g. <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code> or <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>&gt;</span></code></li> <li>an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> object</li> <li>a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> pointer</li> <li>wide characters (<code class=highlight><span class=kt>wchar_t</span></code>, <code class=highlight><span class=kt>char16_t</span></code>, <code class=highlight><span class=kt>char32_t</span></code>), which are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8: a wide string object (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>wstring</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u16string</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u32string</span></code>), an array (e.g. a wide string literal), or a pointer to a null-terminated wide string</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd>an input iterator type, for instance a pair of pointers such as <code>ptr</code> and <code>ptr + len</code>, or a pair of <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=o>::</span><span class=n>iterator</span></code>; the iterators of single-byte characters are borrowed or read like the byte inputs above, those of wide characters are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>input</code> (in)</dt> <dd>Input to parse from.</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 ignoLine truncated
+</code></pre></div> <ol> <li>Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).</li> <li>Deserialize from a pair of input iterators.</li> </ol> <p>Both overloads accept the same <abbr title="JavaScript Object Notation">JSON</abbr> text as <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a>, with the same <code>ignore_comments</code>/<code>ignore_trailing_commas</code> options, but build a <a href=../ ><code>basic_json_document</code></a> (a flat index into the input) instead of a tree of <code>BasicJsonType</code> values. They accept every input <code>BasicJsonType::parse()</code> takes, and in addition a pointer to a null-terminated wide string (which <code>BasicJsonType::parse()</code> rejects). Contiguous inputs of single-byte characters that stay alive can be borrowed; all others (streams, <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code>, wide characters, which must be converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8, and non-contiguous iterators) are read into a copy that the document owns -- see the Notes. Use <a href=../parse_copy/ ><code>parse_copy()</code></a> to get an owned copy of a borrowable input as well.</p> <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>a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code>, a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string_view</span></code> (C++17), or a C-style array of single-byte characters</li> <li>a pointer to a null-terminated string of single-byte characters (<code class=highlight><span class=kt>char</span></code>, <code class=highlight><span class=kt>signed</span><span class=w> </span><span class=kt>char</span></code>, <code class=highlight><span class=kt>unsigned</span><span class=w> </span><span class=kt>char</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span></code>)</li> <li>a container for which <code class=highlight><span class=n>obj</span><span class=p>.</span><span class=n>data</span><span class=p>()</span></code> and <code class=highlight><span class=n>obj</span><span class=p>.</span><span class=n>size</span><span class=p>()</span></code> give contiguous single-byte access, e.g. <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code> or <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>&gt;</span></code></li> <li>an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> object</li> <li>a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> pointer</li> <li>wide characters (<code class=highlight><span class=kt>wchar_t</span></code>, <code class=highlight><span class=kt>char16_t</span></code>, <code class=highlight><span class=kt>char32_t</span></code>), which are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8: a wide string object (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>wstring</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u16string</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u32string</span></code>), an array (e.g. a wide string literal), or a pointer to a null-terminated wide string</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd>an input iterator type, for instance a pair of pointers such as <code>ptr</code> and <code>ptr + len</code>, or a pair of <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=o>::</span><span class=n>iterator</span></code>; the iterators of single-byte characters are borrowed or read like the byte inputs above, those of wide characters are converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8</dd> </dl> <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> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>input</code> (in)</dt> <dd>Input to parse from.</dLine truncated
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;string&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json_view.hpp&gt;</span>
@@ -71,4 +71,4 @@
 <span class=p>}</span>
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=kc>true</span><span class=w> </span><span class=mi>2</span>
 <span class=kc>false</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../parse_copy/ >parse_copy</a> - deserialize a copy of a compatible input</li> <li><a href=../accept/ >accept</a> - check whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../read/ >read</a> - (re-)parse into this document, reusing its memory</li> <li><a href=../owns_source/ >owns_source</a> - return whether the document holds its own copy of the text</li> <li><a href=../load/ >load</a> - read a document from an image instead of parsing <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../../basic_json/parse/ ><code>BasicJsonType::parse</code></a> - the corresponding function of <code>basic_json</code></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 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 21, 2026 08:21:29 UTC">October 21, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><patLine 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=../parse_copy/ >parse_copy</a> - deserialize a copy of a compatible input</li> <li><a href=../accept/ >accept</a> - check whether the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../read/ >read</a> - (re-)parse into this document, reusing its memory</li> <li><a href=../owns_source/ >owns_source</a> - return whether the document holds its own copy of the text</li> <li><a href=../load/ >load</a> - read a document from an image instead of parsing <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../../basic_json/parse/ ><code>BasicJsonType::parse</code></a> - the corresponding function of <code>basic_json</code></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 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>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>.</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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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=Line truncated
@@ -19,14 +19,14 @@ static basic_json_document parse(IteratorType first, IteratorType last,
 1. Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
 1. Deserialize from a pair of input iterators.

-Both overloads accept the same JSON text as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), with the same `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (a flat index into the input) instead of a tree of `BasicJsonType` values. They take the same inputs as `BasicJsonType::parse()`. Byte inputs that stay alive can be borrowed; all others (streams, `FILE*`, wide characters, non-contiguous iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) to get an owned copy of a borrowable input as well.
+Both overloads accept the same JSON text as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), with the same `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (a flat index into the input) instead of a tree of `BasicJsonType` values. They accept every input `BasicJsonType::parse()` takes, and in addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of single-byte characters that stay alive can be borrowed; all others (streams, `FILE*`, wide characters, which must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](https://json.nlohmann.me/api/basic_json_document/parse_copy/index.md) to get an owned copy of a borrowable input as well.

 ## Template parameters

 `InputType` : A compatible input, for instance:

 ```
- a `std::string`, `std::string_view`, or a C-style array of single-byte characters
+- a `std::string`, a `std::string_view` (C++17), or a C-style array of single-byte characters
 - a pointer to a null-terminated string of single-byte characters (`char`, `signed char`,
  `unsigned char`, `std::uint8_t`)
 - a container for which `obj.data()` and `obj.size()` give contiguous single-byte access, e.g.
@@ -40,6 +40,8 @@ Both overloads accept the same JSON text as [`BasicJsonType::parse()`](https://j

 `IteratorType` : an input iterator type, for instance a pair of pointers such as `ptr` and `ptr + len`, or a pair of `std::string::iterator`; the iterators of single-byte characters are borrowed or read like the byte inputs above, those of wide characters are converted to UTF-8

+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).
+
 ## Parameters

 `input` (in) : Input to parse from.
@@ -179,3 +181,4 @@ false
 ## Version history

 - Added in version 3.13.0 unreleased.
+- 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`.
@@ -0,0 +1,18 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a valid JSON text, given as UTF-16
+    const std::u16string valid_text = u"{\"name\":\"\u00e9\"}";
+
+    // an invalid JSON text, given as UTF-16
+    const std::u16string invalid_text = u"{\"name\":\"\u00e9\",}";
+
+    std::cout << std::boolalpha
+              << json::accept(valid_text) << ' '
+              << json::accept(invalid_text) << '\n';
+}
@@ -0,0 +1 @@
+true false
@@ -0,0 +1,27 @@
+#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';
+}
@@ -0,0 +1,6 @@
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+{"name":"é"}
+[1,2,3]
+{"name":"é"}
@@ -108,6 +108,18 @@ which avoids repeating it:
    
    ```

+!!! info "Getting values out of a document or a view"
+
+    A [view](../api/basic_json_view/index.md) offers the same `get<T>()` conversion. For the built-in types (booleans,
+    numbers, strings, `#!cpp std::vector`, `#!cpp std::map`, ...) it reads the value straight from the document's
+    index, without building a `basic_json` value first; user-defined types with a `from_json()` are converted from a
+    `basic_json` value, see the [list](../api/basic_json_view/get.md). Two conversions never copy at all:
+    [`get_string()`](../api/basic_json_view/get_string.md) returns a string as a view into the source text, and
+    [`number_token()`](../api/basic_json_view/number_token.md) returns a number exactly as it was written. Every other
+    type is obtained from a subtree that is built on demand with
+    [`materialize()`](../api/basic_json_view/materialize.md). See
+    [Zero-copy JSON views](json_view.md#getting-values-out-without-copying).
+
 The library already knows how to convert to and from the scalar types and the STL containers (such as
 `#!cpp std::vector`, `#!cpp std::map`, `#!cpp std::array`, `#!cpp std::optional`, and many more). Converting a JSON
 object back to a `#!cpp std::map` or a JSON array back to a `#!cpp std::vector` therefore works without any extra code:
@@ -304,3 +316,4 @@ The conversions above are built in for standard types. To make the same syntax w
 - [`get_ref`](../api/basic_json/get_ref.md) / [`get_ptr`](../api/basic_json/get_ptr.md) - access the stored value without copying
 - [Arbitrary types conversions](arbitrary_types.md) - support your own types
 - [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) - toggle implicit conversions
+- [Zero-copy JSON views](json_view.md) - get values out of a document or a view
@@ -73,7 +73,7 @@
 <span class=kc>null</span><span class=p>:</span><span class=w> </span><span class=kc>null</span>
 <span class=kc>nu</span><span class=err>mber</span><span class=p>:</span><span class=w> </span><span class=p>{</span><span class=nt>"floating-point"</span><span class=p>:</span><span class=mf>17.23</span><span class=p>,</span><span class=nt>"integer"</span><span class=p>:</span><span class=mi>42</span><span class=p>}</span>
 <span class=err>s</span><span class=kc>tr</span><span class=err>i</span><span class=kc>n</span><span class=err>g</span><span class=p>:</span><span class=w> </span><span class=s2>"Hello, world!"</span>
-</code></pre></div> </details> <p>The library already knows how to convert to and from the scalar types and the <abbr title="Standard Template Library">STL</abbr> containers (such as <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>array</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>optional</span></code>, and many more). Converting a <abbr title="JavaScript Object Notation">JSON</abbr> object back to a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code> or a <abbr title="JavaScript Object Notation">JSON</abbr> array back to a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> therefore works without any extra code:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{{</span><span class=s>"one"</span><span class=p>,</span><span class=w> </span><span class=mi>1</span><span class=p>},</span><span class=w> </span><span class=p>{</span><span class=s>"two"</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>}};</span>
+</code></pre></div> </details> <div class="admonition info"> <p class=admonition-title>Getting values out of a document or a view</p> <p>A <a href=../../api/basic_json_view/ >view</a> offers the same <code>get&lt;T&gt;()</code> conversion. For the built-in types (booleans, numbers, strings, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code>, ...) it reads the value straight from the document's index, without building a <code>basic_json</code> value first; user-defined types with a <code>from_json()</code> are converted from a <code>basic_json</code> value, see the <a href=../../api/basic_json_view/get/ >list</a>. Two conversions never copy at all: <a href=../../api/basic_json_view/get_string/ ><code>get_string()</code></a> returns a string as a view into the source text, and <a href=../../api/basic_json_view/number_token/ ><code>number_token()</code></a> returns a number exactly as it was written. Every other type is obtained from a subtree that is built on demand with <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a>. See <a href=../json_view/#getting-values-out-without-copying>Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a>.</p> </div> <p>The library already knows how to convert to and from the scalar types and the <abbr title="Standard Template Library">STL</abbr> containers (such as <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>array</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>optional</span></code>, and many more). Converting a <abbr title="JavaScript Object Notation">JSON</abbr> object back to a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span></code> or a <abbr title="JavaScript Object Notation">JSON</abbr> array back to a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> therefore works without any extra code:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{{</span><span class=s>"one"</span><span class=p>,</span><span class=w> </span><span class=mi>1</span><span class=p>},</span><span class=w> </span><span class=p>{</span><span class=s>"two"</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>}};</span>
 <span class=k>auto</span><span class=w> </span><span class=n>m</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span><span class=w> </span><span class=kt>int</span><span class=o>&gt;&gt;</span><span class=p>();</span><span class=w>  </span><span class=c1>// {{"one", 1}, {"two", 2}}</span>
 </code></pre></div> <p><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>pair</span></code> and <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>tuple</span></code> are also supported, converting positionally to and from a <abbr title="JavaScript Object Notation">JSON</abbr> array:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{</span><span class=mf>1.0</span><span class=p>,</span><span class=w> </span><span class=s>"hello"</span><span class=p>,</span><span class=w> </span><span class=mi>42</span><span class=p>};</span>
 <span class=k>auto</span><span class=w> </span><span class=n>t</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>j</span><span class=p>.</span><span class=n>get</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=n>tuple</span><span class=o>&lt;</span><span class=kt>double</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>,</span><span class=w> </span><span class=kt>int</span><span class=o>&gt;&gt;</span><span class=p>();</span><span class=w>  </span><span class=c1>// {1.0, "hello", 42}</span>
@@ -113,4 +113,4 @@
 </code></pre></div> <div class="admonition info"> <p class=admonition-title>Constructing from a C++20 range view</p> <p>A <code>json</code> array can also be constructed directly from a C++20 range view (<code>std::ranges::view</code>), such as the result of <code>std::views::filter</code> or <code>std::views::transform</code> -- no intermediate container is needed:</p> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=kt>int</span><span class=o>&gt;</span><span class=w> </span><span class=n>nums</span><span class=p>{</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>,</span><span class=w> </span><span class=mi>37</span><span class=p>,</span><span class=w> </span><span class=mi>42</span><span class=p>,</span><span class=w> </span><span class=mi>21</span><span class=p>};</span>
 <span class=k>auto</span><span class=w> </span><span class=n>filtered</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nums</span><span class=w> </span><span class=o>|</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>views</span><span class=o>::</span><span class=n>filter</span><span class=p>([](</span><span class=kt>int</span><span class=w> </span><span class=n>i</span><span class=p>)</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>i</span><span class=w> </span><span class=o>&gt;</span><span class=w> </span><span class=mi>10</span><span class=p>;</span><span class=w> </span><span class=p>});</span>
 <span class=n>json</span><span class=w> </span><span class=nf>j</span><span class=p>(</span><span class=n>filtered</span><span class=p>);</span><span class=w>   </span><span class=c1>// [37,42,21]</span>
-</code></pre></div> <p>This requires <a href=../../api/macros/json_has_ranges/ ><code>JSON_HAS_RANGES</code></a> to be enabled and is unavailable on MinGW due to incomplete C++20 ranges support there; see <a href=../../api/macros/json_has_range_view_conversion/ ><code>JSON_HAS_RANGE_VIEW_CONVERSION</code></a>.</p> </div> <h2 id=your-own-types>Your own types<a class=headerlink href=#your-own-types title="Permanent link">&para;</a></h2> <p>The conversions above are built in for standard types. To make the same syntax work for <strong>your own</strong> types, provide <code>to_json</code>/<code>from_json</code> functions (or use one of the convenience macros). This is described in detail on the <a href=../arbitrary_types/ >arbitrary types conversions</a> page. Enums can be mapped to strings as described in <a href=../enum_conversion/ >specializing enum conversion</a>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/get/ ><code>get</code></a> - get a copy converted to a given type</li> <li><a href=../../api/basic_json/get_to/ ><code>get_to</code></a> - convert into an existing variable</li> <li><a href=../../api/basic_json/get_ref/ ><code>get_ref</code></a> / <a href=../../api/basic_json/get_ptr/ ><code>get_ptr</code></a> - access the stored value without copying</li> <li><a href=../arbitrary_types/ >Arbitrary types conversions</a> - support your own types</li> <li><a href=../../api/macros/json_use_implicit_conversions/ ><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> - toggle implicit conversions</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 11, 2026 06:21:51 UTC">October 11, 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 &copy; 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-1Line truncated
+</code></pre></div> <p>This requires <a href=../../api/macros/json_has_ranges/ ><code>JSON_HAS_RANGES</code></a> to be enabled and is unavailable on MinGW due to incomplete C++20 ranges support there; see <a href=../../api/macros/json_has_range_view_conversion/ ><code>JSON_HAS_RANGE_VIEW_CONVERSION</code></a>.</p> </div> <h2 id=your-own-types>Your own types<a class=headerlink href=#your-own-types title="Permanent link">&para;</a></h2> <p>The conversions above are built in for standard types. To make the same syntax work for <strong>your own</strong> types, provide <code>to_json</code>/<code>from_json</code> functions (or use one of the convenience macros). This is described in detail on the <a href=../arbitrary_types/ >arbitrary types conversions</a> page. Enums can be mapped to strings as described in <a href=../enum_conversion/ >specializing enum conversion</a>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/get/ ><code>get</code></a> - get a copy converted to a given type</li> <li><a href=../../api/basic_json/get_to/ ><code>get_to</code></a> - convert into an existing variable</li> <li><a href=../../api/basic_json/get_ref/ ><code>get_ref</code></a> / <a href=../../api/basic_json/get_ptr/ ><code>get_ptr</code></a> - access the stored value without copying</li> <li><a href=../arbitrary_types/ >Arbitrary types conversions</a> - support your own types</li> <li><a href=../../api/macros/json_use_implicit_conversions/ ><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> - toggle implicit conversions</li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - get values out of a document or a view</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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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-.7Line truncated
@@ -100,6 +100,10 @@ number: {"floating-point":17.23,"integer":42}
 string: "Hello, world!"
 ```

+Getting values out of a document or a view
+
+A [view](https://json.nlohmann.me/api/basic_json_view/index.md) offers the same `get<T>()` conversion. For the built-in types (booleans, numbers, strings, `std::vector`, `std::map`, ...) it reads the value straight from the document's index, without building a `basic_json` value first; user-defined types with a `from_json()` are converted from a `basic_json` value, see the [list](https://json.nlohmann.me/api/basic_json_view/get/index.md). Two conversions never copy at all: [`get_string()`](https://json.nlohmann.me/api/basic_json_view/get_string/index.md) returns a string as a view into the source text, and [`number_token()`](https://json.nlohmann.me/api/basic_json_view/number_token/index.md) returns a number exactly as it was written. Every other type is obtained from a subtree that is built on demand with [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md). See [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#getting-values-out-without-copying).
+
 The library already knows how to convert to and from the scalar types and the STL containers (such as `std::vector`, `std::map`, `std::array`, `std::optional`, and many more). Converting a JSON object back to a `std::map` or a JSON array back to a `std::vector` therefore works without any extra code:

 ```
@@ -246,3 +250,4 @@ The conversions above are built in for standard types. To make the same syntax w
 - [`get_ref`](https://json.nlohmann.me/api/basic_json/get_ref/index.md) / [`get_ptr`](https://json.nlohmann.me/api/basic_json/get_ptr/index.md) - access the stored value without copying
 - [Arbitrary types conversions](https://json.nlohmann.me/features/arbitrary_types/index.md) - support your own types
 - [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) - toggle implicit conversions
+- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - get values out of a document or a view
@@ -1,7 +1,9 @@
 # Creating JSON values

 There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text
-instead, see [parsing](parsing/index.md).
+instead, see [parsing](parsing/index.md). A JSON text can also be parsed into a
+[document](../api/basic_json_document/index.md) and read through a [view](../api/basic_json_view/index.md) instead of
+into a value; see [Zero-copy JSON views](json_view.md).

 ## From C++ values

@@ -118,3 +120,4 @@ string `#!json "42"`.
 - [`operator""_json`](../api/operator_literal_json.md) - the `_json` literal
 - [Converting values](conversions.md) - which C++ types can be used
 - [Parsing](parsing/index.md) - create a value from JSON text
+- [Zero-copy JSON views](json_view.md) - create a document and a view from JSON text instead of a value
@@ -1,4 +1,4 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/creating_values/" rel="canonical"><link href=../conversions/ rel=prev><link href=../element_access/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Creating JSON values - 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=#creating-json-values 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> Creating JSON values </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"Line truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/creating_values/" rel="canonical"><link href=../conversions/ rel=prev><link href=../element_access/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Creating JSON values - 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=#creating-json-values 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> Creating JSON values </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"Line truncated
 <span class=n>json</span><span class=w> </span><span class=n>j_float</span><span class=w>   </span><span class=o>=</span><span class=w> </span><span class=mf>3.141</span><span class=p>;</span>
 <span class=n>json</span><span class=w> </span><span class=n>j_string</span><span class=w>  </span><span class=o>=</span><span class=w> </span><span class=s>"Hello"</span><span class=p>;</span>
 <span class=n>json</span><span class=w> </span><span class=n>j_boolean</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>;</span>
@@ -42,4 +42,4 @@
 <span class=w>  </span><span class=nt>"answer"</span><span class=p>:</span><span class=w> </span><span class=mi>42</span><span class=p>,</span>
 <span class=w>  </span><span class=nt>"hello"</span><span class=p>:</span><span class=w> </span><span class=s2>"world"</span>
 <span class=p>}</span>
-</code></pre></div> </details> <p>Note this <strong>parses</strong> the string, so <code class=highlight><span class=s>"42"</span><span class=n>_json</span></code> is the number <code class=highlight><span class=mi>42</span></code>, whereas <code class=highlight><span class=n>json</span><span class=p>(</span><span class=s>"42"</span><span class=p>)</span></code> is the <abbr title="JavaScript Object Notation">JSON</abbr> string <code class=highlight><span class=s2>"42"</span></code>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/basic_json/ ><code>basic_json</code> constructors</a> - all ways to construct a value</li> <li><a href=../../api/basic_json/array/ ><code>array</code></a> / <a href=../../api/basic_json/object/ ><code>object</code></a> - force array or object type</li> <li><a href=../../api/operator_literal_json/ ><code>operator""_json</code></a> - the <code>_json</code> literal</li> <li><a href=../conversions/ >Converting values</a> - which C++ types can be used</li> <li><a href=../parsing/ >Parsing</a> - create a value from <abbr title="JavaScript Object Notation">JSON</abbr> text</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="July 4, 2026 09:13:25 UTC">July 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons:Line truncated
+</code></pre></div> </details> <p>Note this <strong>parses</strong> the string, so <code class=highlight><span class=s>"42"</span><span class=n>_json</span></code> is the number <code class=highlight><span class=mi>42</span></code>, whereas <code class=highlight><span class=n>json</span><span class=p>(</span><span class=s>"42"</span><span class=p>)</span></code> is the <abbr title="JavaScript Object Notation">JSON</abbr> string <code class=highlight><span class=s2>"42"</span></code>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/basic_json/ ><code>basic_json</code> constructors</a> - all ways to construct a value</li> <li><a href=../../api/basic_json/array/ ><code>array</code></a> / <a href=../../api/basic_json/object/ ><code>object</code></a> - force array or object type</li> <li><a href=../../api/operator_literal_json/ ><code>operator""_json</code></a> - the <code>_json</code> literal</li> <li><a href=../conversions/ >Converting values</a> - which C++ types can be used</li> <li><a href=../parsing/ >Parsing</a> - create a value from <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - create a document and a view from <abbr title="JavaScript Object Notation">JSON</abbr> text instead of a value</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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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="wwLine truncated
@@ -1,6 +1,6 @@
 # Creating JSON values

-There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text instead, see [parsing](https://json.nlohmann.me/features/parsing/index.md).
+There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text instead, see [parsing](https://json.nlohmann.me/features/parsing/index.md). A JSON text can also be parsed into a [document](https://json.nlohmann.me/api/basic_json_document/index.md) and read through a [view](https://json.nlohmann.me/api/basic_json_view/index.md) instead of into a value; see [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md).

 ## From C++ values

@@ -105,3 +105,4 @@ Note this **parses** the string, so `"42"_json` is the number `42`, whereas `jso
 - [`operator""_json`](https://json.nlohmann.me/api/operator_literal_json/index.md) - the `_json` literal
 - [Converting values](https://json.nlohmann.me/features/conversions/index.md) - which C++ types can be used
 - [Parsing](https://json.nlohmann.me/features/parsing/index.md) - create a value from JSON text
+- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - create a document and a view from JSON text instead of a value
@@ -287,6 +287,23 @@ external dependency and is not defined by default.

 See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md).

+## `JSON_VIEW_NO_SIMD`
+
+When defined, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) uses only portable C++ to scan strings, instead of vector instructions (SSE2 on x86-64,
+NEON on AArch64). The same input is accepted or rejected either way; only the speed differs. It is not defined by
+default.
+
+See [full documentation of `JSON_VIEW_NO_SIMD`](../api/macros/json_view_no_simd.md).
+
+## `JSON_VIEW_USE_SSSE3`
+
+When defined on x86-64, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) validates non-ASCII text in strings with SSSE3 without asking the CPU first. It is not
+defined by default.
+
+See [full documentation of `JSON_VIEW_USE_SSSE3`](../api/macros/json_view_use_ssse3.md).
+
 ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`

 The library defines 12 macros to simplify the serialization/deserialization of types. See the page on
@@ -1 +1 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/macros/" rel="canonical"><link href=../enum_conversion/ rel=prev><link href=../trailing_commas/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Supported Macros - 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=#supported-macros 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> Supported Macros </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </labelLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/macros/" rel="canonical"><link href=../enum_conversion/ rel=prev><link href=../trailing_commas/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Supported Macros - 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=#supported-macros 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> Supported Macros </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </labelLine truncated
@@ -218,6 +218,18 @@ When defined, UTF-8 validation of JSON strings read from contiguous byte input i

 See [full documentation of `JSON_USE_SIMDUTF`](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md).

+## `JSON_VIEW_NO_SIMD`
+
+When defined, the parser of [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (`<nlohmann/json_view.hpp>`) uses only portable C++ to scan strings, instead of vector instructions (SSE2 on x86-64, NEON on AArch64). The same input is accepted or rejected either way; only the speed differs. It is not defined by default.
+
+See [full documentation of `JSON_VIEW_NO_SIMD`](https://json.nlohmann.me/api/macros/json_view_no_simd/index.md).
+
+## `JSON_VIEW_USE_SSSE3`
+
+When defined on x86-64, the parser of [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) (`<nlohmann/json_view.hpp>`) validates non-ASCII text in strings with SSSE3 without asking the CPU first. It is not defined by default.
+
+See [full documentation of `JSON_VIEW_USE_SSSE3`](https://json.nlohmann.me/api/macros/json_view_use_ssse3/index.md).
+
 ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`

 The library defines 12 macros to simplify the serialization/deserialization of types. See the page on [arbitrary type conversion](https://json.nlohmann.me/features/arbitrary_types/#simplify-your-life-with-macros) for a detailed discussion.
@@ -126,6 +126,18 @@ json a = {1, 2, 3, 4};
 a.erase(1);             // [1,3,4]  (erase by index)
 ```

+## Editing a document
+
+The operations above work on a `basic_json` value. A JSON text that was parsed into a
+[document](json_view.md#editing-a-document) can also be changed in place, without building a `basic_json` tree for the
+parts that are not touched: [`set`](../api/basic_json_document/set.md) replaces a value, adds or replaces an object
+member, or replaces an array element (also through a JSON pointer),
+[`push_back`](../api/basic_json_document/push_back.md) appends to an array,
+[`insert`](../api/basic_json_document/insert.md) inserts into an array (unlike `basic_json::insert`, it has no object
+overload; members are added with `set`), and [`erase`](../api/basic_json_document/erase.md) removes a member or an
+element. These functions are available on the
+editable document types, such as [`json_editable_document`](../api/json_editable_document.md).
+
 ## See also

 - [`push_back`](../api/basic_json/push_back.md) / [`emplace_back`](../api/basic_json/emplace_back.md) - append to an array
@@ -134,3 +146,4 @@ a.erase(1);             // [1,3,4]  (erase by index)
 - [`merge_patch`](../api/basic_json/merge_patch.md) - apply an RFC 7396 merge patch
 - [`erase`](../api/basic_json/erase.md) / [`clear`](../api/basic_json/clear.md) - remove elements
 - [JSON Patch and Diff](json_patch.md) and [JSON Merge Patch](merge_patch.md) - structured modifications
+- [Editing a document](json_view.md#editing-a-document) - change a parsed document in place
@@ -1,4 +1,4 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/modifying_values/" rel="canonical"><link href=../json_pointer/ rel=prev><link href=../modules/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Modifying values - 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=#modifying-values 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> Modifying values </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label>Line truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/modifying_values/" rel="canonical"><link href=../json_pointer/ rel=prev><link href=../modules/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Modifying values - 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=#modifying-values 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> Modifying values </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label>Line truncated
 <span class=n>j</span><span class=p>.</span><span class=n>push_back</span><span class=p>(</span><span class=mi>1</span><span class=p>);</span><span class=w>         </span><span class=c1>// [1]</span>
 <span class=n>j</span><span class=p>.</span><span class=n>push_back</span><span class=p>(</span><span class=mi>2</span><span class=p>);</span><span class=w>         </span><span class=c1>// [1,2]</span>
 <span class=n>j</span><span class=p>.</span><span class=n>emplace_back</span><span class=p>(</span><span class=mi>3</span><span class=p>);</span><span class=w>      </span><span class=c1>// [1,2,3]</span>
@@ -60,4 +60,4 @@

 <span class=n>json</span><span class=w> </span><span class=n>a</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>,</span><span class=w> </span><span class=mi>3</span><span class=p>,</span><span class=w> </span><span class=mi>4</span><span class=p>};</span>
 <span class=n>a</span><span class=p>.</span><span class=n>erase</span><span class=p>(</span><span class=mi>1</span><span class=p>);</span><span class=w>             </span><span class=c1>// [1,3,4]  (erase by index)</span>
-</code></pre></div> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/push_back/ ><code>push_back</code></a> / <a href=../../api/basic_json/emplace_back/ ><code>emplace_back</code></a> - append to an array</li> <li><a href=../../api/basic_json/emplace/ ><code>emplace</code></a> - insert into an object if the key is absent</li> <li><a href=../../api/basic_json/update/ ><code>update</code></a> - merge objects (shallow, or recursive with <code>merge_objects</code>)</li> <li><a href=../../api/basic_json/merge_patch/ ><code>merge_patch</code></a> - apply an <abbr title="Request for Comments">RFC</abbr> 7396 merge patch</li> <li><a href=../../api/basic_json/erase/ ><code>erase</code></a> / <a href=../../api/basic_json/clear/ ><code>clear</code></a> - remove elements</li> <li><a href=../json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> and <a href=../merge_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</a> - structured modifications</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 14, 2026 15:40:55 UTC">October 14, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C1Line truncated
+</code></pre></div> <h2 id=editing-a-document>Editing a document<a class=headerlink href=#editing-a-document title="Permanent link">&para;</a></h2> <p>The operations above work on a <code>basic_json</code> value. A <abbr title="JavaScript Object Notation">JSON</abbr> text that was parsed into a <a href=../json_view/#editing-a-document>document</a> can also be changed in place, without building a <code>basic_json</code> tree for the parts that are not touched: <a href=../../api/basic_json_document/set/ ><code>set</code></a> replaces a value, adds or replaces an object member, or replaces an array element (also through a <abbr title="JavaScript Object Notation">JSON</abbr> pointer), <a href=../../api/basic_json_document/push_back/ ><code>push_back</code></a> appends to an array, <a href=../../api/basic_json_document/insert/ ><code>insert</code></a> inserts into an array (unlike <code>basic_json::insert</code>, it has no object overload; members are added with <code>set</code>), and <a href=../../api/basic_json_document/erase/ ><code>erase</code></a> removes a member or an element. These functions are available on the editable document types, such as <a href=../../api/json_editable_document/ ><code>json_editable_document</code></a>.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/push_back/ ><code>push_back</code></a> / <a href=../../api/basic_json/emplace_back/ ><code>emplace_back</code></a> - append to an array</li> <li><a href=../../api/basic_json/emplace/ ><code>emplace</code></a> - insert into an object if the key is absent</li> <li><a href=../../api/basic_json/update/ ><code>update</code></a> - merge objects (shallow, or recursive with <code>merge_objects</code>)</li> <li><a href=../../api/basic_json/merge_patch/ ><code>merge_patch</code></a> - apply an <abbr title="Request for Comments">RFC</abbr> 7396 merge patch</li> <li><a href=../../api/basic_json/erase/ ><code>erase</code></a> / <a href=../../api/basic_json/clear/ ><code>clear</code></a> - remove elements</li> <li><a href=../json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> and <a href=../merge_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</a> - structured modifications</li> <li><a href=../json_view/#editing-a-document>Editing a document</a> - change a parsed document in place</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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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-.3Line truncated
@@ -111,6 +111,10 @@ json a = {1, 2, 3, 4};
 a.erase(1);             // [1,3,4]  (erase by index)
 ```

+## Editing a document
+
+The operations above work on a `basic_json` value. A JSON text that was parsed into a [document](https://json.nlohmann.me/features/json_view/#editing-a-document) can also be changed in place, without building a `basic_json` tree for the parts that are not touched: [`set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) replaces a value, adds or replaces an object member, or replaces an array element (also through a JSON pointer), [`push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md) appends to an array, [`insert`](https://json.nlohmann.me/api/basic_json_document/insert/index.md) inserts into an array (unlike `basic_json::insert`, it has no object overload; members are added with `set`), and [`erase`](https://json.nlohmann.me/api/basic_json_document/erase/index.md) removes a member or an element. These functions are available on the editable document types, such as [`json_editable_document`](https://json.nlohmann.me/api/json_editable_document/index.md).
+
 ## See also

 - [`push_back`](https://json.nlohmann.me/api/basic_json/push_back/index.md) / [`emplace_back`](https://json.nlohmann.me/api/basic_json/emplace_back/index.md) - append to an array
@@ -119,3 +123,4 @@ a.erase(1);             // [1,3,4]  (erase by index)
 - [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) - apply an RFC 7396 merge patch
 - [`erase`](https://json.nlohmann.me/api/basic_json/erase/index.md) / [`clear`](https://json.nlohmann.me/api/basic_json/clear/index.md) - remove elements
 - [JSON Patch and Diff](https://json.nlohmann.me/features/json_patch/index.md) and [JSON Merge Patch](https://json.nlohmann.me/features/merge_patch/index.md) - structured modifications
+- [Editing a document](https://json.nlohmann.me/features/json_view/#editing-a-document) - change a parsed document in place
@@ -18,6 +18,7 @@ flowchart LR
 The [`parse`](../../api/basic_json/parse.md) function reads a JSON value from an input. The input can be

 - a string (`#!cpp std::string`, C string, or string literal),
+- a wide string (`#!cpp std::u16string`, `#!cpp std::u32string`, or `#!cpp std::wstring`, or a wide string literal),
 - a `#!cpp std::istream` (e.g., an `#!cpp std::ifstream` reading from a file),
 - a `#!cpp FILE*` pointer,
 - a pair of iterators over a contiguous range (e.g., a `#!cpp std::vector<std::uint8_t>`), or
@@ -32,12 +33,18 @@ std::ifstream f("example.json");
 json data = json::parse(f);
 ```

-The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value.
+The input must be encoded in UTF-8; other encodings are not supported. The exception is wide-character input, which
+is read as UTF-16 or UTF-32 -- depending on the character type -- and converted to UTF-8; see the
+[`parse`](../../api/basic_json/parse.md) page for an example. A single input may contain only one JSON value.
 Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](json_lines.md) format.

 By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the `parse`
 function — see [comments](../comments.md) and [trailing commas](../trailing_commas.md).

+[`basic_json_document::parse`](../../api/basic_json_document/parse.md) accepts the same inputs with the same options,
+but keeps the result in a document rather than in a `basic_json` value; see
+[Documents and views](#documents-and-views) below.
+
 ## Strictness and trailing data

 [`parse`](../../api/basic_json/parse.md) reads a single JSON value and requires the whole input to be consumed: any
@@ -98,6 +105,26 @@ The library offers two parsing models:
 You can influence a DOM parse without switching to the SAX interface by passing a
 [parser callback](parser_callbacks.md), which is called during parsing and can, for example, discard parts of the input.

+## Documents and views
+
+A third model sits between DOM and SAX: [`basic_json_document::parse`](../../api/basic_json_document/parse.md) parses
+the input into a document that keeps the text and a flat index of the values in it, and
+[`basic_json_view`](../../api/basic_json_view/index.md) gives read-only access to the values through that index.
+The whole input is validated during parsing, but only integers and strings that contain escape sequences are converted
+right away (the strings into a buffer owned by the document). Floating-point numbers and all other strings stay in the
+source text and are only converted when they are read, which is faster and uses less memory than building a tree of `basic_json` values when only parts
+of the document are needed. A document can also be
+modified in place, and it can be saved and loaded again without parsing it.
+
+```cpp
+#include <nlohmann/json_view.hpp>
+
+json_document doc = json_document::parse(R"({"happy": true, "pi": 3.141})");
+std::cout << doc.root()["happy"].get<bool>() << '\n';
+```
+
+See [Zero-copy JSON views](../json_view.md) for the concept and the trade-offs.
+
 ## Exceptions

 When the input is not valid JSON, the `parse` function throws an exception by default. If exceptions are undesired or
@@ -108,6 +135,7 @@ options.
 ## See also

 - [`parse`](../../api/basic_json/parse.md) - deserialize from a compatible input
+- [`basic_json_document::parse`](../../api/basic_json_document/parse.md) - deserialize into a document instead of a value
 - [`accept`](../../api/basic_json/accept.md) - check if the input is valid JSON
 - [`sax_parse`](../../api/basic_json/sax_parse.md) - generate SAX events
 - [JSON Lines](json_lines.md) - parse newline-delimited JSON
@@ -115,3 +143,4 @@ options.
 - [SAX interface](sax_interface.md) - implement a custom SAX handler
 - [parsing and exceptions](parse_exceptions.md) - control error handling
 - [parsing untrusted input](untrusted_input.md) - what to consider when parsing input from untrusted sources
+- [Zero-copy JSON views](../json_view.md) - parse into a document and read it through a view
@@ -1,13 +1,17 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/" rel="canonical"><link href=../performance/ rel=prev><link href=json_lines/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parsing - 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=#parsing 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> Parsing </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-componeLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/" rel="canonical"><link href=../performance/ rel=prev><link href=json_lines/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parsing - 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=#parsing 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> Parsing </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-componeLine truncated
    I["JSON input"] --&gt; P["parse()"]
    I --&gt; S["sax_parse()"]
    I --&gt; A["accept()"]
    P --&gt;|"optional parser callback filters values"| D["basic_json value (DOM)"]
    S --&gt; H["events delivered to a user SAX handler"]
-    A --&gt; V["bool: is the input valid JSON?"]</code></pre> <h2 id=input>Input<a class=headerlink href=#input title="Permanent link">&para;</a></h2> <p>The <a href=../../api/basic_json/parse/ ><code>parse</code></a> function reads a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input. The input can be</p> <ul> <li>a string (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code>, C string, or string literal),</li> <li>a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (e.g., an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code> reading from a file),</li> <li>a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> pointer,</li> <li>a pair of iterators over a contiguous range (e.g., a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>&gt;</span></code>), or</li> <li>a contiguous container.</li> </ul> <div class=highlight><pre><span></span><code><span class=c1>// parse from a string</span>
+    A --&gt; V["bool: is the input valid JSON?"]</code></pre> <h2 id=input>Input<a class=headerlink href=#input title="Permanent link">&para;</a></h2> <p>The <a href=../../api/basic_json/parse/ ><code>parse</code></a> function reads a <abbr title="JavaScript Object Notation">JSON</abbr> value from an input. The input can be</p> <ul> <li>a string (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code>, C string, or string literal),</li> <li>a wide string (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u16string</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>u32string</span></code>, or <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>wstring</span></code>, or a wide string literal),</li> <li>a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (e.g., an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code> reading from a file),</li> <li>a <code class=highlight><span class=kt>FILE</span><span class=o>*</span></code> pointer,</li> <li>a pair of iterators over a contiguous range (e.g., a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>&lt;</span><span class=n>std</span><span class=o>::</span><span class=kt>uint8_t</span><span class=o>&gt;</span></code>), or</li> <li>a contiguous container.</li> </ul> <div class=highlight><pre><span></span><code><span class=c1>// parse from a string</span>
 <span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span><span class=s>{"happy": true, "pi": 3.141}</span><span class=dl>)</span><span class=s>"</span><span class=p>);</span>

 <span class=c1>// parse from a file</span>
 <span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>f</span><span class=p>(</span><span class=s>"example.json"</span><span class=p>);</span>
 <span class=n>json</span><span class=w> </span><span class=n>data</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
-</code></pre></div> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <h2 id=strictness-and-trailing-data>Strictness and trailing data<a class=headerlink href=#strictness-and-trailing-data title="Permanent link">&para;</a></h2> <p><a href=../../api/basic_json/parse/ ><code>parse</code></a> reads a single <abbr title="JavaScript Object Notation">JSON</abbr> value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete <abbr title="JavaScript Object Notation">JSON</abbr> document.</p> <p><a href=../../api/operator_gtgt/ ><code>operator&gt;&gt;</code></a> follows relaxed <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> semantics instead: it parses one <abbr title="JavaScript Object Notation">JSON</abbr> value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one <abbr title="JavaScript Object Notation">JSON</abbr> document, prefer <code>parse</code>.</p> <p>When using <code>operator&gt;&gt;</code> to read several concatenated values this way, a value that is a number must be followed by whitespace, because <code>operator&gt;&gt;</code> consumes the character that terminates a number, unless <a href=../../api/macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code> — see the <a href=../../api/operator_gtgt/#notes><code>operator&gt;&gt;</code> notes</a> for details and examples.</p> <h2 id=input-sources-and-performance>Input sources and performance<a class=headerlink href=#input-sources-and-performance title="Permanent link">&para;</a></h2> <p>All inputs produce the same values and the same exceptions, but they are read in different ways, which makes some of them faster than others:</p> <table> <thead> <tr> <th>input</th> <th>how it is read</th> </tr> </thead> <tbody> <tr> <td>strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory</td> <td>the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span></code>, ...)</td> <td>the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up</td> </tr> <tr> <td><code class=highlight><span class=kt>FILE</span><span class=o>*</span></code></td> <td>one character at a time, with the file locked once for the whole parse</td> </tr> <tr> <td>other iterator ranges (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istreambuf_iterator</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code>), wide strings</td> <td>one character at a time</td> </tr> </tbody> </table> <p>Parsing a file from a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code> is therefore only about 10 to 20 % slower than reading the whole file into a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> first and parsing that, and it needs no memory for a copy of the file. The stream is never read ahead: after parsing, it is positioned exactly as if every character had been read one at a time, so <a href=../../api/operator_gtgt/ ><code>operator&gt;&gt;</code></a> can still read several values from one stream (see also <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a>).</p> <Line truncated
+</code></pre></div> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. The exception is wide-character input, which is read as <abbr title="Unicode Transformation Format">UTF</abbr>-16 or <abbr title="Unicode Transformation Format">UTF</abbr>-32 -- depending on the character type -- and converted to <abbr title="Unicode Transformation Format">UTF</abbr>-8; see the <a href=../../api/basic_json/parse/ ><code>parse</code></a> page for an example. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <p><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> accepts the same inputs with the same options, but keeps the result in a document rather than in a <code>basic_json</code> value; see <a href=#documents-and-views>Documents and views</a> below.</p> <h2 id=strictness-and-trailing-data>Strictness and trailing data<a class=headerlink href=#strictness-and-trailing-data title="Permanent link">&para;</a></h2> <p><a href=../../api/basic_json/parse/ ><code>parse</code></a> reads a single <abbr title="JavaScript Object Notation">JSON</abbr> value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete <abbr title="JavaScript Object Notation">JSON</abbr> document.</p> <p><a href=../../api/operator_gtgt/ ><code>operator&gt;&gt;</code></a> follows relaxed <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> semantics instead: it parses one <abbr title="JavaScript Object Notation">JSON</abbr> value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one <abbr title="JavaScript Object Notation">JSON</abbr> document, prefer <code>parse</code>.</p> <p>When using <code>operator&gt;&gt;</code> to read several concatenated values this way, a value that is a number must be followed by whitespace, because <code>operator&gt;&gt;</code> consumes the character that terminates a number, unless <a href=../../api/macros/json_precise_stream_position/ ><code>JSON_PRECISE_STREAM_POSITION</code></a> is defined to <code>1</code> — see the <a href=../../api/operator_gtgt/#notes><code>operator&gt;&gt;</code> notes</a> for details and examples.</p> <h2 id=input-sources-and-performance>Input sources and performance<a class=headerlink href=#input-sources-and-performance title="Permanent link">&para;</a></h2> <p>All inputs produce the same values and the same exceptions, but they are read in different ways, which makes some of them faster than others:</p> <table> <thead> <tr> <th>input</th> <th>how it is read</th> </tr> </thead> <tbody> <tr> <td>strings, string views, string literals, contiguous containers, pointer or iterator ranges over contiguous memory</td> <td>the whole input is scanned in bulk: runs of string characters, numbers, and indentation are recognized several bytes at a time</td> </tr> <tr> <td><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code> (<code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istringstream</span></code>, ...)</td> <td>the characters the stream buffer holds are scanned in bulk like a string; the stream buffer is asked for more when they are used up</td> </tr> <tr> <td><code class=highlight><span class=kt>FILE</span><span class=o>*</span></code></td> <td>one character at a time, with the file locked once for the whole parse</td> </tr> <tr> <td>other iterator ranges (e.g., <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>list</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code>, <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istreambuf_iterator</span><span class=o>&lt;</span><span class=kt>char</span><span class=o>&gt;</span></code>), wide strings</td> <td>one character at a time</td> </tr> </tbody> </table> <p>Parsing a file from a <code class=highlight><span claLine truncated
+
+<span class=n>json_document</span><span class=w> </span><span class=n>doc</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json_document</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=sa>R</span><span class=s>"</span><span class=dl>(</span><span class=s>{"happy": true, "pi": 3.141}</span><span class=dl>)</span><span class=s>"</span><span class=p>);</span>
+<span class=n>std</span><span class=o>::</span><span class=n>cout</span><span class=w> </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=n>doc</span><span class=p>.</span><span class=n>root</span><span class=p>()[</span><span class=s>"happy"</span><span class=p>].</span><span class=n>get</span><span class=o>&lt;</span><span class=kt>bool</span><span class=o>&gt;</span><span class=p>()</span><span class=w> </span><span class=o>&lt;&lt;</span><span class=w> </span><span class=sc>'\n'</span><span class=p>;</span>
+</code></pre></div> <p>See <a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> for the concept and the trade-offs.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <p>When the input is not valid <abbr title="JavaScript Object Notation">JSON</abbr>, the <code>parse</code> function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or <a href=../../api/basic_json/accept/ ><code>accept</code></a> can be used to only check whether an input is valid <abbr title="JavaScript Object Notation">JSON</abbr>. See <a href=parse_exceptions/ >parsing and exceptions</a> for the available options.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse</code></a> - deserialize into a document instead of a value</li> <li><a href=../../api/basic_json/accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> - parse newline-delimited <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=parser_callbacks/ >parser callbacks</a> - influence the parsing by a callback function</li> <li><a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - implement a custom <abbr title="Simple API for XML">SAX</abbr> handler</li> <li><a href=parse_exceptions/ >parsing and exceptions</a> - control error handling</li> <li><a href=untrusted_input/ >parsing untrusted input</a> - what to consider when parsing input from untrusted sources</li> <li><a href=../json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - parse into a document and read it through a view</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 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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-2Line truncated
@@ -17,6 +17,7 @@ flowchart LR
 The [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) function reads a JSON value from an input. The input can be

 - a string (`std::string`, C string, or string literal),
+- a wide string (`std::u16string`, `std::u32string`, or `std::wstring`, or a wide string literal),
 - a `std::istream` (e.g., an `std::ifstream` reading from a file),
 - a `FILE*` pointer,
 - a pair of iterators over a contiguous range (e.g., a `std::vector<std::uint8_t>`), or
@@ -31,10 +32,12 @@ std::ifstream f("example.json");
 json data = json::parse(f);
 ```

-The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value. Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](https://json.nlohmann.me/features/parsing/json_lines/index.md) format.
+The input must be encoded in UTF-8; other encodings are not supported. The exception is wide-character input, which is read as UTF-16 or UTF-32 -- depending on the character type -- and converted to UTF-8; see the [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) page for an example. A single input may contain only one JSON value. Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](https://json.nlohmann.me/features/parsing/json_lines/index.md) format.

 By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the `parse` function — see [comments](https://json.nlohmann.me/features/comments/index.md) and [trailing commas](https://json.nlohmann.me/features/trailing_commas/index.md).

+[`basic_json_document::parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) accepts the same inputs with the same options, but keeps the result in a document rather than in a `basic_json` value; see [Documents and views](#documents-and-views) below.
+
 ## Strictness and trailing data

 [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) reads a single JSON value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete JSON document.
@@ -69,6 +72,19 @@ The library offers two parsing models:

 You can influence a DOM parse without switching to the SAX interface by passing a [parser callback](https://json.nlohmann.me/features/parsing/parser_callbacks/index.md), which is called during parsing and can, for example, discard parts of the input.

+## Documents and views
+
+A third model sits between DOM and SAX: [`basic_json_document::parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) parses the input into a document that keeps the text and a flat index of the values in it, and [`basic_json_view`](https://json.nlohmann.me/api/basic_json_view/index.md) gives read-only access to the values through that index. The whole input is validated during parsing, but only integers and strings that contain escape sequences are converted right away (the strings into a buffer owned by the document). Floating-point numbers and all other strings stay in the source text and are only converted when they are read, which is faster and uses less memory than building a tree of `basic_json` values when only parts of the document are needed. A document can also be modified in place, and it can be saved and loaded again without parsing it.
+
+```
+#include <nlohmann/json_view.hpp>
+
+json_document doc = json_document::parse(R"({"happy": true, "pi": 3.141})");
+std::cout << doc.root()["happy"].get<bool>() << '\n';
+```
+
+See [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) for the concept and the trade-offs.
+
 ## Exceptions

 When the input is not valid JSON, the `parse` function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or [`accept`](https://json.nlohmann.me/api/basic_json/accept/index.md) can be used to only check whether an input is valid JSON. See [parsing and exceptions](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) for the available options.
@@ -76,6 +92,7 @@ When the input is not valid JSON, the `parse` function throws an exception by de
 ## See also

 - [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
+- [`basic_json_document::parse`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) - deserialize into a document instead of a value
 - [`accept`](https://json.nlohmann.me/api/basic_json/accept/index.md) - check if the input is valid JSON
 - [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) - generate SAX events
 - [JSON Lines](https://json.nlohmann.me/features/parsing/json_lines/index.md) - parse newline-delimited JSON
@@ -83,3 +100,4 @@ When the input is not valid JSON, the `parse` function throws an exception by de
 - [SAX interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) - implement a custom SAX handler
 - [parsing and exceptions](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) - control error handling
 - [parsing untrusted input](https://json.nlohmann.me/features/parsing/untrusted_input/index.md) - what to consider when parsing input from untrusted sources
+- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - parse into a document and read it through a view
@@ -81,6 +81,9 @@ Invalid UTF-8 is rejected while parsing, not just while serializing:

 - In JSON text, an ill-formed UTF-8 byte in a string is a
  [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) ("invalid string: ill-formed UTF-8 byte").
+- In UTF-16 or UTF-32 input, an ill-formed sequence is a
+  [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) as well: a lone surrogate, a high surrogate
+  that is not followed by its low surrogate, and a code point above `U+10FFFF` are all rejected.
 - In a binary format, a string that is not valid UTF-8 is a
  [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113).

@@ -1 +1 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/untrusted_input/" rel="canonical"><link href=../sax_interface/ rel=prev><link href=../../assertions/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parsing Untrusted Input - 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=#parsing-untrusted-input 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> Parsing Untrusted Input </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9Line truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/untrusted_input/" rel="canonical"><link href=../sax_interface/ rel=prev><link href=../../assertions/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parsing Untrusted Input - 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=#parsing-untrusted-input 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> Parsing Untrusted Input </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9Line truncated
@@ -39,6 +39,7 @@ For the binary formats, an announced size is never trusted outright:
 Invalid UTF-8 is rejected while parsing, not just while serializing:

 - In JSON text, an ill-formed UTF-8 byte in a string is a [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101) ("invalid string: ill-formed UTF-8 byte").
+- In UTF-16 or UTF-32 input, an ill-formed sequence is a [`parse_error.101`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error101) as well: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above `U+10FFFF` are all rejected.
 - In a binary format, a string that is not valid UTF-8 is a [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113).

 A `'\0'` (NUL) byte *inside* a quoted JSON string is always rejected (it must be escaped as `\u0000`). A NUL byte *outside* of a string is different: by default it is silently treated as the end of the input, so trailing bytes after it -- including further, otherwise well-formed JSON -- are silently ignored rather than rejected. Since untrusted input that happens to embed a NUL is a way to make part of it disappear without a parse error, see the [FAQ entry](https://json.nlohmann.me/home/faq/#nul-bytes-in-the-input) and consider defining [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) to `1` to reject a NUL byte like any other unexpected byte instead.
@@ -1,7 +1,7 @@
 # Debugging

-This page collects the library's built-in debugger integrations and other debugging-related features. They are
-not linked from a single place elsewhere in the docs, so are collected here.
+This page collects the library's built-in debugger integrations and other debugging-related features. They are not
+covered by any single page elsewhere in the docs, so they are collected here.

 ## Visual Studio (natvis)

@@ -1,3 +1,3 @@
-<!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/home/debugging/" rel="canonical"><link href=../sponsors/ rel=prev><link href=../../features/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Debugging - 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=#debugging 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> Debugging </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-coLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/home/debugging/" rel="canonical"><link href=../sponsors/ rel=prev><link href=../../features/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Debugging - 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=#debugging 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> Debugging </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-coLine truncated
 </code></pre></div> </li> <li> <p>Generate a Natvis file with the tags of your configuration, for example for <code>JSON_DIAGNOSTICS</code>, <code>JSON_DIAGNOSTIC_POSITIONS</code>, and <code>JSON_VIEW_NO_SIMD</code>:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>natvis<span class=w> </span><span class=nv>NATVIS_ARGS</span><span class=o>=</span><span class=s2>"--abi-tags _diag,_dp,_vns --output my_nlohmann_json.natvis"</span>
-</code></pre></div> </li> <li> <p>Use the generated file instead of <code>nlohmann_json.natvis</code>.</p> </li> </ol> <p><code>--abi-tags</code> can be repeated for several configurations, and <code>--all</code> generates every combination (about 60 MB for 12 ABI tags, doubling with each further tag). See <a href="https://github.com/nlohmann/json/tree/develop/tools/generate_natvis"><code>tools/generate_natvis</code></a> for all options.</p> <p>Debug engines that wrap LLDB instead of the <abbr title="Microsoft Visual C++">MSVC</abbr> debug engine (for example, <code>codelldb</code> in VS Code) only have partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the <code>.natvis</code> file present. Switching to <code>cppvsdbg</code> where available, or checking your debug extension's own Natvis support/version, are the next things to try if this happens. There is currently no bundled LLDB-native pretty-printer script in this repository.</p> <h2 id=gdb>GDB<a class=headerlink href=#gdb title="Permanent link">&para;</a></h2> <p>The repository ships a <a href="https://github.com/nlohmann/json/tree/develop/tools/gdb_pretty_printer">GDB Python pretty printer</a> under <code>tools/gdb_pretty_printer</code>, with its own usage instructions in that directory's <code>README.md</code>.</p> <h2 id=extended-exception-diagnostics>Extended exception diagnostics<a class=headerlink href=#extended-exception-diagnostics title="Permanent link">&para;</a></h2> <p>Defining <a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> before including the library augments <code>type_error</code>/<code>out_of_range</code>-style exceptions with a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer to the offending value, which can help pinpoint where in a large document a runtime error occurred. This only applies to exceptions thrown <em>after</em> a value exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not covered by this mechanism -- see <a href=../../features/parsing/parse_exceptions/ >Parsing and exceptions</a> for how parse errors report their own location instead.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 21, 2026 20:57:54 UTC">October 21, 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 &copy; 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-67Line truncated
+</code></pre></div> </li> <li> <p>Use the generated file instead of <code>nlohmann_json.natvis</code>.</p> </li> </ol> <p><code>--abi-tags</code> can be repeated for several configurations, and <code>--all</code> generates every combination (about 60 MB for 12 ABI tags, doubling with each further tag). See <a href="https://github.com/nlohmann/json/tree/develop/tools/generate_natvis"><code>tools/generate_natvis</code></a> for all options.</p> <p>Debug engines that wrap LLDB instead of the <abbr title="Microsoft Visual C++">MSVC</abbr> debug engine (for example, <code>codelldb</code> in VS Code) only have partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the <code>.natvis</code> file present. Switching to <code>cppvsdbg</code> where available, or checking your debug extension's own Natvis support/version, are the next things to try if this happens. There is currently no bundled LLDB-native pretty-printer script in this repository.</p> <h2 id=gdb>GDB<a class=headerlink href=#gdb title="Permanent link">&para;</a></h2> <p>The repository ships a <a href="https://github.com/nlohmann/json/tree/develop/tools/gdb_pretty_printer">GDB Python pretty printer</a> under <code>tools/gdb_pretty_printer</code>, with its own usage instructions in that directory's <code>README.md</code>.</p> <h2 id=extended-exception-diagnostics>Extended exception diagnostics<a class=headerlink href=#extended-exception-diagnostics title="Permanent link">&para;</a></h2> <p>Defining <a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> before including the library augments <code>type_error</code>/<code>out_of_range</code>-style exceptions with a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer to the offending value, which can help pinpoint where in a large document a runtime error occurred. This only applies to exceptions thrown <em>after</em> a value exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not covered by this mechanism -- see <a href=../../features/parsing/parse_exceptions/ >Parsing and exceptions</a> for how parse errors report their own location instead.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 25, 2026 05:18:07 UTC">October 25, 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 &copy; 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-67Line truncated
@@ -1,6 +1,6 @@
 # Debugging

-This page collects the library's built-in debugger integrations and other debugging-related features. They are not linked from a single place elsewhere in the docs, so are collected here.
+This page collects the library's built-in debugger integrations and other debugging-related features. They are not covered by any single page elsewhere in the docs, so they are collected here.

 ## Visual Studio (natvis)

@@ -143,7 +143,8 @@ As this global context comes at the price of storing one additional pointer per

    Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.

-See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information.
+See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information, and
+[Debugging](debugging.md) for the debugger integrations of the library.

 ## Parse errors

@@ -78,7 +78,7 @@
 <span class=w>    </span><span class=p>}</span>
 <span class=p>}</span>
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.302] (/address/housenumber) type must be number, but is string
-</code></pre></div> <p>Now the exception message contains a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer <code>/address/housenumber</code> that indicates which value has the wrong type.</p> </details> <p>See <a href=../../api/macros/json_diagnostics/ >documentation of <code>JSON_DIAGNOSTICS</code></a> for more information.</p> <h2 id=parse-errors>Parse errors<a class=headerlink href=#parse-errors title="Permanent link">&para;</a></h2> <p>The library throws this exception when a parse error occurs. Parse errors can occur during the deserialization of <abbr title="JavaScript Object Notation">JSON</abbr> text or of one of the binary formats (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>), as well as when using <abbr title="JavaScript Object Notation">JSON</abbr> Patch.</p> <p>Exceptions have ids 1xx.</p> <div class="admonition info"> <p class=admonition-title>Byte index</p> <p>Member <code>byte</code> holds the byte index of the last read character in the input file.</p> <p>For an input with n bytes, 1 is the index of the first character and n+1 is the index of the terminating null byte or the end of file. This also holds true when reading a byte vector (<abbr title="Concise Binary Object Representation">CBOR</abbr> or MessagePack).</p> </div> <details class=example> <summary>Example: catch a <code>parse_error</code> exception</summary> <p>The following code shows how a <code>parse_error</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
+</code></pre></div> <p>Now the exception message contains a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer <code>/address/housenumber</code> that indicates which value has the wrong type.</p> </details> <p>See <a href=../../api/macros/json_diagnostics/ >documentation of <code>JSON_DIAGNOSTICS</code></a> for more information, and <a href=../debugging/ >Debugging</a> for the debugger integrations of the library.</p> <h2 id=parse-errors>Parse errors<a class=headerlink href=#parse-errors title="Permanent link">&para;</a></h2> <p>The library throws this exception when a parse error occurs. Parse errors can occur during the deserialization of <abbr title="JavaScript Object Notation">JSON</abbr> text or of one of the binary formats (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>), as well as when using <abbr title="JavaScript Object Notation">JSON</abbr> Patch.</p> <p>Exceptions have ids 1xx.</p> <div class="admonition info"> <p class=admonition-title>Byte index</p> <p>Member <code>byte</code> holds the byte index of the last read character in the input file.</p> <p>For an input with n bytes, 1 is the index of the first character and n+1 is the index of the terminating null byte or the end of file. This also holds true when reading a byte vector (<abbr title="Concise Binary Object Representation">CBOR</abbr> or MessagePack).</p> </div> <details class=example> <summary>Example: catch a <code>parse_error</code> exception</summary> <p>The following code shows how a <code>parse_error</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</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>
@@ -309,4 +309,4 @@ array index 18446744073709551616 exceeds size_type
 exception id: 501
 </code></pre></div> </details> <h3 id=jsonexceptionother_error501>json.exception.other_error.501<a class=headerlink href=#jsonexceptionother_error501 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch operation 'test' failed. The unsuccessful operation is also printed.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Executing <code class=highlight><span class=p>{</span><span class=nt>"op"</span><span class=p>:</span><span class=s2>"test"</span><span class=p>,</span><span class=w> </span><span class=nt>"path"</span><span class=p>:</span><span class=s2>"/baz"</span><span class=p>,</span><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=s2>"bar"</span><span class=p>}</span></code> on <code class=highlight><span class=p>{</span><span class=nt>"baz"</span><span class=p>:</span><span class=w> </span><span class=s2>"qux"</span><span class=p>}</span></code>:</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
 </code></pre></div> </div> <h3 id=jsonexceptionother_error502>json.exception.other_error.502<a class=headerlink href=#jsonexceptionother_error502 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson</code></a> and <a href=../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a> were called with <code>use_type = true</code> but <code>use_size = false</code>. <abbr title="Universal Binary JSON">UBJSON</abbr> requires a size marker (<code>#</code>) after a type marker (<code>$</code>).</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.502] use_type requires use_size = true
-</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 21, 2026 08:36:31 UTC">October 21, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.Line truncated
+</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 25, 2026 05:18:07 UTC">October 25, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.Line truncated
@@ -139,7 +139,7 @@ Output:

 Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.

-See [documentation of `JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) for more information.
+See [documentation of `JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) for more information, and [Debugging](https://json.nlohmann.me/home/debugging/index.md) for the debugger integrations of the library.

 ## Parse errors

@@ -81,8 +81,9 @@ rejected by default, and the library never adds them when serializing.

 The library supports **Unicode input** as follows:

- Only **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
+- **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
+- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively; `std::wstring` works as well and is interpreted as UTF-16 or UTF-32, depending on the width of the platform's `wchar_t`. These encodings cannot be read from a `FILE*` or a `std::istream`, which carry bytes only.
+- Ill-formed UTF-16 or UTF-32 input is 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. The same holds for iterators over 2- or 4-byte characters.
 - Other encodings such as Latin-1 or ISO 8859-1 are **not** supported and will yield parse or serialization errors.
 - The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
 - Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
@@ -146,7 +147,7 @@ json::parse(std::string("\"") + '\0' + "\""); // throws parse_error.101: control

    Why are wide strings (e.g., `std::wstring`) dumped as arrays of numbers?

-As described [above](#parse-errors-reading-non-ascii-characters), the library assumes UTF-8 as encoding.  To store a wide string, you need to change the encoding.
+As described [above](#parse-errors-reading-non-ascii-characters), the library stores its strings as UTF-8. To store a wide string as a string, convert it to a UTF-8 encoded `std::string` first, as in the example below.

 !!! example

@@ -8,7 +8,7 @@

 <span class=n>json</span><span class=w> </span><span class=n>obj</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>{{</span><span class=s>"key"</span><span class=p>,</span><span class=w> </span><span class=s>"value"</span><span class=p>}};</span>
 <span class=n>json</span><span class=w> </span><span class=n>j</span><span class=p>{</span><span class=n>obj</span><span class=p>};</span><span class=w>   </span><span class=c1>// -&gt; {"key":"value"}  (copy, not array)</span>
-</code></pre></div> <p>Without the macro (default behavior), <code>json j{obj}</code> creates <code>[{"key":"value"}]</code>. This opt-in macro fixes issue #5074 while preserving backwards compatibility for existing code.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">&para;</a></h2> <h3 id=relaxed-parsing>Relaxed parsing<a class=headerlink href=#relaxed-parsing title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Can you add an option to ignore trailing commas?</p> </div> <p>Yes, trailing commas in arrays and objects can be allowed by setting parameter <code>ignore_trailing_commas</code> of <a href=../../api/basic_json/parse/ ><code>parse</code></a> to <code class=highlight><span class=nb>true</span></code>; see <a href=../../features/trailing_commas/ >trailing commas</a>. They are rejected by default, and the library never adds them when serializing.</p> <h3 id=parse-errors-reading-non-ascii-characters>Parse errors reading non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters<a class=headerlink href=#parse-errors-reading-non-ascii-characters title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why is the parser complaining about a Chinese character?</li> <li>Does the library support Unicode?</li> <li>I get an exception <code>[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"</code></li> </ul> </div> <p>The library supports <strong>Unicode input</strong> as follows:</p> <ul> <li>Only <strong><abbr title="Unicode Transformation Format">UTF</abbr>-8</strong> encoded input is supported, which is the default encoding for <abbr title="JavaScript Object Notation">JSON</abbr>, according to <a href="https://tools.ietf.org/html/rfc8259.html#section-8.1"><abbr title="Request for Comments">RFC</abbr> 8259</a>.</li> <li><code>std::u16string</code> and <code>std::u32string</code> can be parsed, assuming <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.</li> <li>Other encodings such as Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 are <strong>not</strong> supported and will yield parse or serialization errors.</li> <li>The library will not replace <a href="http://www.unicode.org/faq/private_use.html#nonchar1">Unicode noncharacters</a>.</li> <li>Invalid surrogates (e.g., incomplete pairs such as <code>\uDEAD</code>) will yield parse errors.</li> <li>The strings stored in the library are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. When using the default string type (<code>std::string</code>), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.</li> <li>When you store strings with different encodings in the library, calling <a href=../../api/basic_json/dump/ ><code>dump()</code></a> may throw an exception unless <code>json::error_handler_t::replace</code>, <code>json::error_handler_t::ignore</code>, or <code>json::error_handler_t::keep</code> are used as error handlers.</li> </ul> <p>In most cases, the parser is right to complain, because the input is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 is often the standard encoding.</p> <h3 id=nul-bytes-in-the-input>NUL bytes in the input<a class=headerlink href=#nul-bytes-in-the-input title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why does <a href=../../api/basic_json/parse/ ><code>json::parse()</code></a> silently ignore part of my input?</li> <li>Why does a <code>std::string</code>/buffer with extra data after the <abbr title="JavaScript Object Notation">JSON</abbr> text parse without error, while a similar-looking string with extra text does not?</li> </ul> </div> <p>A <code>'\0'</code> (NUL) byte anywhere in the input is treated the same as the real end of the input, rather than as an ordinary (and, outside of a string, invalid) byte. Everything from that byte onward is silently ignored, without a parse error — including further, otherwise well-formed <abbr title="JavaScript Object Notation">JSON</abbr>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w>Line truncated
+</code></pre></div> <p>Without the macro (default behavior), <code>json j{obj}</code> creates <code>[{"key":"value"}]</code>. This opt-in macro fixes issue #5074 while preserving backwards compatibility for existing code.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">&para;</a></h2> <h3 id=relaxed-parsing>Relaxed parsing<a class=headerlink href=#relaxed-parsing title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Can you add an option to ignore trailing commas?</p> </div> <p>Yes, trailing commas in arrays and objects can be allowed by setting parameter <code>ignore_trailing_commas</code> of <a href=../../api/basic_json/parse/ ><code>parse</code></a> to <code class=highlight><span class=nb>true</span></code>; see <a href=../../features/trailing_commas/ >trailing commas</a>. They are rejected by default, and the library never adds them when serializing.</p> <h3 id=parse-errors-reading-non-ascii-characters>Parse errors reading non-<abbr title="American Standard Code for Information Interchange">ASCII</abbr> characters<a class=headerlink href=#parse-errors-reading-non-ascii-characters title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why is the parser complaining about a Chinese character?</li> <li>Does the library support Unicode?</li> <li>I get an exception <code>[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"</code></li> </ul> </div> <p>The library supports <strong>Unicode input</strong> as follows:</p> <ul> <li><strong><abbr title="Unicode Transformation Format">UTF</abbr>-8</strong> encoded input is supported, which is the default encoding for <abbr title="JavaScript Object Notation">JSON</abbr>, according to <a href="https://tools.ietf.org/html/rfc8259.html#section-8.1"><abbr title="Request for Comments">RFC</abbr> 8259</a>.</li> <li><code>std::u16string</code> and <code>std::u32string</code> can be parsed, assuming <abbr title="Unicode Transformation Format">UTF</abbr>-16 and <abbr title="Unicode Transformation Format">UTF</abbr>-32 encoding, respectively; <code>std::wstring</code> works as well and is interpreted as <abbr title="Unicode Transformation Format">UTF</abbr>-16 or <abbr title="Unicode Transformation Format">UTF</abbr>-32, depending on the width of the platform's <code>wchar_t</code>. These encodings cannot be read from a <code>FILE*</code> or a <code>std::istream</code>, which carry bytes only.</li> <li>Ill-formed <abbr title="Unicode Transformation Format">UTF</abbr>-16 or <abbr title="Unicode Transformation Format">UTF</abbr>-32 input is 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 parse error. The same holds for iterators over 2- or 4-byte characters.</li> <li>Other encodings such as Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 are <strong>not</strong> supported and will yield parse or serialization errors.</li> <li>The library will not replace <a href="http://www.unicode.org/faq/private_use.html#nonchar1">Unicode noncharacters</a>.</li> <li>Invalid surrogates (e.g., incomplete pairs such as <code>\uDEAD</code>) will yield parse errors.</li> <li>The strings stored in the library are <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. When using the default string type (<code>std::string</code>), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.</li> <li>When you store strings with different encodings in the library, calling <a href=../../api/basic_json/dump/ ><code>dump()</code></a> may throw an exception unless <code>json::error_handler_t::replace</code>, <code>json::error_handler_t::ignore</code>, or <code>json::error_handler_t::keep</code> are used as error handlers.</li> </ul> <p>In most cases, the parser is right to complain, because the input is not <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or <abbr title="International Organization for Standardization">ISO</abbr> 8859-1 is often the standard encoding.</p> <h3 id=nul-bytes-in-the-input>NUL bytes in the input<a class=headerlink href=#nul-bytes-in-the-input title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why does <a href=../../api/basic_json/parse/ ><code>json::parse()</code></a> silently ignore part of my input?</li> <li>Why does a <code>std::string</code>/buffer with extra data after the <abbr title="JavaScript Object Notation">JSON</abbr> text parse without error, while a similar-looking string with extra text does not?</li> </ul> </div> <p>A <code>'\0'</codLine truncated
 <span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=s>"true"</span><span class=p>);</span><span class=w> </span><span class=c1>// == 123, the "true" is silently ignored too</span>
 </code></pre></div> <p>This is different from any other unexpected trailing byte, which <em>does</em> raise <a href=../exceptions/#jsonexceptionparse_error101><code>parse_error.101</code></a>:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"123x"</span><span class=p>);</span><span class=w> </span><span class=c1>// throws parse_error.101: unexpected additional data</span>
 </code></pre></div> <p>This falls out of the same convention used when no explicit input length is given at all: <code>json::parse(const char*)</code> already stops at the first NUL byte via <code>strlen()</code>, since a bare pointer has no length of its own. The library applies that same NUL-terminated-C-string convention uniformly, rather than only when a length is genuinely unavailable — so a <code>std::string</code>, iterator range, or container whose content happens to include a NUL byte is affected the same way a raw <code>const char*</code> would be.</p> <p>If your input may contain a trailing or embedded NUL that is <strong>not</strong> meant to signal the end of the <abbr title="JavaScript Object Notation">JSON</abbr> text — for instance, a fixed-size, zero-padded buffer — trim it yourself before calling <code>parse()</code>, since the library will otherwise silently stop there instead of raising an error:</p> <div class=highlight><pre><span></span><code><span class=n>s</span><span class=p>.</span><span class=n>resize</span><span class=p>(</span><span class=n>s</span><span class=p>.</span><span class=n>find</span><span class=p>(</span><span class=sc>'\0'</span><span class=p>));</span><span class=w> </span><span class=c1>// drop everything from the first NUL onward, if any</span>
@@ -18,7 +18,7 @@

 <span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"123"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=p>);</span><span class=w> </span><span class=c1>// throws parse_error.101 instead of silently returning 123</span>
 </code></pre></div> <p>This macro defaults to <code>0</code> (disabled, preserving the behavior described above) to avoid breaking existing code that may depend on it, even unknowingly; it is planned to become the default in version 4.0.0. See <a href=../../api/macros/json_strict_nul_handling/ >its documentation</a> for details, including how it also affects <code>char</code> arrays such as string literals.</p> <p>Note that this is unrelated to an <em>unescaped</em> NUL byte occurring <strong>inside</strong> a quoted <abbr title="JavaScript Object Notation">JSON</abbr> string, which is a different, already-invalid case and is correctly rejected either way:</p> <div class=highlight><pre><span></span><code><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=n>string</span><span class=p>(</span><span class=s>"</span><span class=se>\"</span><span class=s>"</span><span class=p>)</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=sc>'\0'</span><span class=w> </span><span class=o>+</span><span class=w> </span><span class=s>"</span><span class=se>\"</span><span class=s>"</span><span class=p>);</span><span class=w> </span><span class=c1>// throws parse_error.101: control character U+0000 (NUL) must be escaped to \u0000</span>
-</code></pre></div> <h3 id=wide-string-handling>Wide string handling<a class=headerlink href=#wide-string-handling title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Why are wide strings (e.g., <code>std::wstring</code>) dumped as arrays of numbers?</p> </div> <p>As described <a href=#parse-errors-reading-non-ascii-characters>above</a>, the library assumes <abbr title="Unicode Transformation Format">UTF</abbr>-8 as encoding. To store a wide string, you need to change the encoding.</p> <div class="admonition example"> <p class=admonition-title>Example</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;codecvt&gt;</span><span class=w> </span><span class=c1>// codecvt_utf8</span>
+</code></pre></div> <h3 id=wide-string-handling>Wide string handling<a class=headerlink href=#wide-string-handling title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Question</p> <p>Why are wide strings (e.g., <code>std::wstring</code>) dumped as arrays of numbers?</p> </div> <p>As described <a href=#parse-errors-reading-non-ascii-characters>above</a>, the library stores its strings as <abbr title="Unicode Transformation Format">UTF</abbr>-8. To store a wide string as a string, convert it to a <abbr title="Unicode Transformation Format">UTF</abbr>-8 encoded <code>std::string</code> first, as in the example below.</p> <div class="admonition example"> <p class=admonition-title>Example</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;codecvt&gt;</span><span class=w> </span><span class=c1>// codecvt_utf8</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;locale&gt;</span><span class=w>  </span><span class=c1>// wstring_convert</span>

 <span class=c1>// encoding function</span>
@@ -56,4 +56,4 @@

 <span class=w>    </span><span class=k>friend</span><span class=w> </span><span class=kt>void</span><span class=w> </span><span class=nf>to_json</span><span class=p>(</span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>Holder</span><span class=o>&amp;</span><span class=w> </span><span class=n>h</span><span class=p>)</span><span class=w> </span><span class=p>{</span><span class=w> </span><span class=cm>/* ... */</span><span class=w> </span><span class=p>}</span>
 <span class=p>};</span>
-</code></pre></div> <p>The <a href=../../api/macros/nlohmann_define_type_intrusive/ ><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code></a> macros define hidden friends as well. See <a href="https://github.com/nlohmann/json/issues/3669">#3669</a> for details.</p> <h3 id=missing-stl-function>Missing <abbr title="Standard Template Library">STL</abbr> function<a class=headerlink href=#missing-stl-function title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why do I get a compilation error <code>'to_string' is not a member of 'std'</code> (or similarly, for <code>strtod</code> or <code>strtof</code>)?</li> <li>Why does the code not compile with MinGW or Android <abbr title="Software Development Kit">SDK</abbr>?</li> </ul> </div> <p>This is not an issue with the code, but rather with the compiler itself. On Android, use a current <abbr title="Native Development Kit">NDK</abbr> (see above). For MinGW, please refer to <a href="http://tehsausage.com/mingw-to-string">this site</a> and <a href="https://github.com/nlohmann/json/issues/136">this discussion</a> for information on how to fix this bug.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 14, 2026 15:40:55 UTC">October 14, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, CLine truncated
+</code></pre></div> <p>The <a href=../../api/macros/nlohmann_define_type_intrusive/ ><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code></a> macros define hidden friends as well. See <a href="https://github.com/nlohmann/json/issues/3669">#3669</a> for details.</p> <h3 id=missing-stl-function>Missing <abbr title="Standard Template Library">STL</abbr> function<a class=headerlink href=#missing-stl-function title="Permanent link">&para;</a></h3> <div class="admonition question"> <p class=admonition-title>Questions</p> <ul> <li>Why do I get a compilation error <code>'to_string' is not a member of 'std'</code> (or similarly, for <code>strtod</code> or <code>strtof</code>)?</li> <li>Why does the code not compile with MinGW or Android <abbr title="Software Development Kit">SDK</abbr>?</li> </ul> </div> <p>This is not an issue with the code, but rather with the compiler itself. On Android, use a current <abbr title="Native Development Kit">NDK</abbr> (see above). For MinGW, please refer to <a href="http://tehsausage.com/mingw-to-string">this site</a> and <a href="https://github.com/nlohmann/json/issues/136">this discussion</a> for information on how to fix this bug.</p> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 25, 2026 05:18:07 UTC">October 25, 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 &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, CLine truncated
@@ -78,8 +78,9 @@ Questions

 The library supports **Unicode input** as follows:

- Only **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
+- **UTF-8** encoded input is supported, which is the default encoding for JSON, according to [RFC 8259](https://tools.ietf.org/html/rfc8259.html#section-8.1).
+- `std::u16string` and `std::u32string` can be parsed, assuming UTF-16 and UTF-32 encoding, respectively; `std::wstring` works as well and is interpreted as UTF-16 or UTF-32, depending on the width of the platform's `wchar_t`. These encodings cannot be read from a `FILE*` or a `std::istream`, which carry bytes only.
+- Ill-formed UTF-16 or UTF-32 input is 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. The same holds for iterators over 2- or 4-byte characters.
 - Other encodings such as Latin-1 or ISO 8859-1 are **not** supported and will yield parse or serialization errors.
 - The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
 - Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
@@ -142,7 +143,7 @@ Question

 Why are wide strings (e.g., `std::wstring`) dumped as arrays of numbers?

-As described [above](#parse-errors-reading-non-ascii-characters), the library assumes UTF-8 as encoding. To store a wide string, you need to change the encoding.
+As described [above](#parse-errors-reading-non-ascii-characters), the library stores its strings as UTF-8. To store a wide string as a string, convert it to a UTF-8 encoded `std::string` first, as in the example below.

 Example

@@ -1 +1 @@
-<!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/home/releases/unreleased/" rel="canonical"><link href=../ rel=prev><link href=../v3.12.0/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Unreleased - 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=#unreleased 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> Unreleased </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div classLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/home/releases/unreleased/" rel="canonical"><link href=../ rel=prev><link href=../v3.12.0/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Unreleased - 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=#unreleased 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> Unreleased </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div classLine truncated
@@ -27,6 +27,7 @@ These changes are part of the `develop` branch, but not of a release yet.
 - [`basic_json::accept`](https://json.nlohmann.me/api/basic_json/accept/index.md): Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
 - [`basic_json::accept`](https://json.nlohmann.me/api/basic_json/accept/index.md): 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)).
 - [`basic_json::accept`](https://json.nlohmann.me/api/basic_json/accept/index.md): 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)).
+- [`basic_json::accept`](https://json.nlohmann.me/api/basic_json/accept/index.md): 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 in version 3.13.0 unreleased; before that, some such sequences were accepted or ended the input silently.
 - [`basic_json::array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md): Made `capacity()` optional, so that array types such as `std::deque` can be used, in version 3.13.0 unreleased.
 - [`basic_json::at`](https://json.nlohmann.me/api/basic_json/at/index.md): Overload 3: Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
 - [`basic_json::basic_json`](https://json.nlohmann.me/api/basic_json/basic_json/index.md): Overload 4: Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0 unreleased.
@@ -86,6 +87,7 @@ These changes are part of the `develop` branch, but not of a release yet.
 - [`basic_json::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md): 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.
 - [`basic_json::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md): 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).
 - [`basic_json::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md): 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`).
+- [`basic_json::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md): 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.
 - [`basic_json::parser_callback_t`](https://json.nlohmann.me/api/basic_json/parser_callback_t/index.md): Fixed in version 3.13.0 unreleased to also remove discarded values from a parent object; before, discarding an array or a value stored under an object key left a discarded member behind, which made the parse result serialize to invalid JSON.
 - [`basic_json::parser_callback_t`](https://json.nlohmann.me/api/basic_json/parser_callback_t/index.md): Fixed in version 3.13.0 unreleased so that discarding an array or object at its start event also hides its content from the callback, as documented above; before, the callback was still called for the content, and the key of every member of a discarded object was kept in memory until the parse ended.
 - [`basic_json::patch`](https://json.nlohmann.me/api/basic_json/patch/index.md): Added [`out_of_range.411`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0 unreleased.
@@ -103,6 +105,7 @@ These changes are part of the `develop` branch, but not of a release yet.
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): `JSON_PRECISE_STREAM_POSITION` added in version 3.13.0 unreleased to optionally leave a `std::istream` positioned right after the parsed value when `strict` is `false`.
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): 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)).
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): 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)).
+- [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): 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.
 - [`std::hash<nlohmann::basic_json>`](https://json.nlohmann.me/api/basic_json/std_hash/index.md): Numbers that compare equal hash equally since version 3.13.0 unreleased; before, `0`, `0U`, and `0.0` had different hash values.
 - [`basic_json::string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md): Removed the requirement that `string_t` be implicitly convertible from `std::string`, which the BSON writer and the UBJSON reader relied on, in version 3.13.0 unreleased.
 - [`basic_json::swap`](https://json.nlohmann.me/api/basic_json/swap/index.md): Overload 1: Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0 unreleased.
@@ -1,4 +1,4 @@
-<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/" rel="canonical"><link href=home/license/ 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 for Modern C++ - 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-for-modern-c 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 for Modern C++ </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay Line truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/" rel="canonical"><link href=home/license/ 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 for Modern C++ - 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-for-modern-c 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 for Modern C++ </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay Line truncated
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</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>
@@ -19,4 +19,4 @@
 vcpkg<span class=w> </span>install<span class=w> </span>nlohmann-json<span class=w>   </span><span class=c1># vcpkg</span>
 </code></pre></div> <div class=highlight><pre><span></span><code><span class=nb>find_package</span><span class=p>(</span><span class=s>nlohmann_json</span><span class=w> </span><span class=s>3.12.0</span><span class=w> </span><span class=s>REQUIRED</span><span class=p>)</span>
 <span class=nb>target_link_libraries</span><span class=p>(</span><span class=s>myproject</span><span class=w> </span><span class=s>PRIVATE</span><span class=w> </span><span class=s>nlohmann_json::nlohmann_json</span><span class=p>)</span>
-</code></pre></div> <p>See <a href=integration/ >Integration</a> for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p> <h2 id=explore-the-documentation>Explore the documentation<a class=headerlink href=#explore-the-documentation title="Permanent link">&para;</a></h2> <div class="grid cards"> <ul> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20.322.75h1.176a1.75 1.75 0 0 1 1.75 1.749v1.177a10.75 10.75 0 0 1-2.925 7.374l-1.228 1.304a24 24 0 0 1-1.596 1.542v5.038c0 .615-.323 1.184-.85 1.5l-4.514 2.709a.75.75 0 0 1-1.12-.488l-.963-4.572a1.3 1.3 0 0 1-.14-.129L8.04 15.96l-1.994-1.873a1.3 1.3 0 0 1-.129-.14l-4.571-.963a.75.75 0 0 1-.49-1.12l2.71-4.514c.316-.527.885-.85 1.5-.85h5.037a24 24 0 0 1 1.542-1.594l1.304-1.23A10.75 10.75 0 0 1 20.321.75Zm-6.344 4.018v-.001l-1.304 1.23a22.3 22.3 0 0 0-3.255 3.851l-2.193 3.29 1.859 1.744.034.034 1.743 1.858 3.288-2.192a22.3 22.3 0 0 0 3.854-3.257l1.228-1.303a9.25 9.25 0 0 0 2.517-6.346V2.5a.25.25 0 0 0-.25-.25h-1.177a9.25 9.25 0 0 0-6.344 2.518M6.5 21c-1.209 1.209-3.901 1.445-4.743 1.49a.24.24 0 0 1-.18-.067.24.24 0 0 1-.067-.18c.045-.842.281-3.534 1.49-4.743.9-.9 2.6-.9 3.5 0s.9 2.6 0 3.5m-.592-8.588L8.17 9.017q.346-.519.717-1.017H5.066a.25.25 0 0 0-.214.121l-2.167 3.612ZM16 15.112q-.5.372-1.018.718l-3.393 2.262.678 3.223 3.612-2.167a.25.25 0 0 0 .121-.214ZM17.5 8a1.5 1.5 0 1 1-3.001-.001A1.5 1.5 0 0 1 17.5 8"/></svg></span> <strong>Features</strong></p> <hr> <p>Creating, parsing, accessing, and serializing <abbr title="JavaScript Object Notation">JSON</abbr> values, <abbr title="JavaScript Object Notation">JSON</abbr> Pointer/Patch, binary formats, and more.</p> <p><a href=features/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> Features</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12.876.64V.639l8.25 4.763c.541.313.875.89.875 1.515v9.525a1.75 1.75 0 0 1-.875 1.516l-8.25 4.762a1.75 1.75 0 0 1-1.75 0l-8.25-4.763a1.75 1.75 0 0 1-.875-1.515V6.917c0-.625.334-1.202.875-1.515L11.126.64a1.75 1.75 0 0 1 1.75 0m-1 1.298L4.251 6.34l7.75 4.474 7.75-4.474-7.625-4.402a.25.25 0 0 0-.25 0m.875 19.123 7.625-4.402a.25.25 0 0 0 .125-.216V7.639l-7.75 4.474ZM3.501 7.64v8.803c0 .09.048.172.125.216l7.625 4.402v-8.947Z"/></svg></span> <strong>Integration</strong></p> <hr> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p><a href=integration/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> Integration</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M0 3.75A.75.75 0 0 1 .75 3h7.497c1.566 0 2.945.8 3.751 2.014A4.5 4.5 0 0 1 15.75 3h7.5a.75.75 0 0 1 .75.75v15.063a.75.75 0 0 1-.755.75l-7.682-.052a3 3 0 0 0-2.142.878l-.89.891a.75.75 0 0 1-1.061 0l-.902-.901a3 3 0 0 0-2.121-.879H.75a.75.75 0 0 1-.75-.75Zm12.75 15.232a4.5 4.5 0 0 1 2.823-.971l6.927.047V4.5h-6.75a3 3 0 0 0-3 3ZM11.247 7.497a3 3 0 0 0-3-2.997H1.5V18h6.947c1.018 0 2.006.346 2.803.98Z"/></svg></span> <strong><abbr title="Application Programming Interface">API</abbr> documentation</strong></p> <hr> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p><a href=api/basic_json/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> <abbr title="Application Programming Interface">API</abbr> documentation</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10.97 8.265a1.45 1.45 0 0 0-.487.57.75.75 0 0 1-1.341-.67c.2-.402.513-.826.997-1.148C10.627 6.69 11.244 6.5 12 6.5c.658 0 1.369.195 1.934.619a2.45 2.45 0 0 1 1.004 2.006c0 1.033-.513 1.72-1.027 2.215-.19.183-.399.358-.579.508l-.147.123a4 4 0 0 0-.435.409v1.37a.75.75 0 1 1-1.5 0v-1.473c0-.237.067-.504.247-.736.22-.28.486-.517.718-.714l.183-.153.001-.001c.172-.143.324-.27.47-.412.368-.355.569-.676.569-1.136a.95.95 0 0 0-.404-.806C12.766 8.118 12.384 8 12 8c-.494 0-.814.121-1.03.265M13 17a1 1 0 1 1-2 0 1 1 0 0 1 2 0"/><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1M2.5 12a9.5 9.5 0 0 0 9.5 9.5 9Line truncated
+</code></pre></div> <p>See <a href=integration/ >Integration</a> for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p> <h2 id=explore-the-documentation>Explore the documentation<a class=headerlink href=#explore-the-documentation title="Permanent link">&para;</a></h2> <div class="grid cards"> <ul> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20.322.75h1.176a1.75 1.75 0 0 1 1.75 1.749v1.177a10.75 10.75 0 0 1-2.925 7.374l-1.228 1.304a24 24 0 0 1-1.596 1.542v5.038c0 .615-.323 1.184-.85 1.5l-4.514 2.709a.75.75 0 0 1-1.12-.488l-.963-4.572a1.3 1.3 0 0 1-.14-.129L8.04 15.96l-1.994-1.873a1.3 1.3 0 0 1-.129-.14l-4.571-.963a.75.75 0 0 1-.49-1.12l2.71-4.514c.316-.527.885-.85 1.5-.85h5.037a24 24 0 0 1 1.542-1.594l1.304-1.23A10.75 10.75 0 0 1 20.321.75Zm-6.344 4.018v-.001l-1.304 1.23a22.3 22.3 0 0 0-3.255 3.851l-2.193 3.29 1.859 1.744.034.034 1.743 1.858 3.288-2.192a22.3 22.3 0 0 0 3.854-3.257l1.228-1.303a9.25 9.25 0 0 0 2.517-6.346V2.5a.25.25 0 0 0-.25-.25h-1.177a9.25 9.25 0 0 0-6.344 2.518M6.5 21c-1.209 1.209-3.901 1.445-4.743 1.49a.24.24 0 0 1-.18-.067.24.24 0 0 1-.067-.18c.045-.842.281-3.534 1.49-4.743.9-.9 2.6-.9 3.5 0s.9 2.6 0 3.5m-.592-8.588L8.17 9.017q.346-.519.717-1.017H5.066a.25.25 0 0 0-.214.121l-2.167 3.612ZM16 15.112q-.5.372-1.018.718l-3.393 2.262.678 3.223 3.612-2.167a.25.25 0 0 0 .121-.214ZM17.5 8a1.5 1.5 0 1 1-3.001-.001A1.5 1.5 0 0 1 17.5 8"/></svg></span> <strong>Features</strong></p> <hr> <p>Creating, parsing, accessing, and serializing <abbr title="JavaScript Object Notation">JSON</abbr> values, <abbr title="JavaScript Object Notation">JSON</abbr> Pointer/Patch, binary formats, zero-copy views, and more.</p> <p><a href=features/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> Features</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12.876.64V.639l8.25 4.763c.541.313.875.89.875 1.515v9.525a1.75 1.75 0 0 1-.875 1.516l-8.25 4.762a1.75 1.75 0 0 1-1.75 0l-8.25-4.763a1.75 1.75 0 0 1-.875-1.515V6.917c0-.625.334-1.202.875-1.515L11.126.64a1.75 1.75 0 0 1 1.75 0m-1 1.298L4.251 6.34l7.75 4.474 7.75-4.474-7.625-4.402a.25.25 0 0 0-.25 0m.875 19.123 7.625-4.402a.25.25 0 0 0 .125-.216V7.639l-7.75 4.474ZM3.501 7.64v8.803c0 .09.048.172.125.216l7.625 4.402v-8.947Z"/></svg></span> <strong>Integration</strong></p> <hr> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p><a href=integration/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> Integration</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M0 3.75A.75.75 0 0 1 .75 3h7.497c1.566 0 2.945.8 3.751 2.014A4.5 4.5 0 0 1 15.75 3h7.5a.75.75 0 0 1 .75.75v15.063a.75.75 0 0 1-.755.75l-7.682-.052a3 3 0 0 0-2.142.878l-.89.891a.75.75 0 0 1-1.061 0l-.902-.901a3 3 0 0 0-2.121-.879H.75a.75.75 0 0 1-.75-.75Zm12.75 15.232a4.5 4.5 0 0 1 2.823-.971l6.927.047V4.5h-6.75a3 3 0 0 0-3 3ZM11.247 7.497a3 3 0 0 0-3-2.997H1.5V18h6.947c1.018 0 2.006.346 2.803.98Z"/></svg></span> <strong><abbr title="Application Programming Interface">API</abbr> documentation</strong></p> <hr> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes, as well as for <code>json_document</code> and <code>json_view</code>.</p> <p><a href=api/basic_json/ ><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13.22 19.03a.75.75 0 0 1 0-1.06L18.19 13H3.75a.75.75 0 0 1 0-1.5h14.44l-4.97-4.97a.749.749 0 0 1 .326-1.275.75.75 0 0 1 .734.215l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0"/></svg></span> <abbr title="Application Programming Interface">API</abbr> documentation</a></p> </li> <li> <p><span class="twemoji lg middle"><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10.97 8.265a1.45 1.45 0 0 0-.487.57.75.75 0 0 1-1.341-.67c.2-.402.513-.826.997-1.148C10.627 6.69 11.244 6.5 12 6.5c.658 0 1.369.195 1.934.619a2.45 2.45 0 0 1 1.004 2.006c0 1.033-.513 1.72-1.027 2.215-.19.183-.399.358-.579.508l-.147.123a4 4 0 0 0-.435.409v1.37a.75.75 0 1 1-1.5 0v-1.473c0-.237.067-.504.247-.736.22-.28.486-.517.718-.714l.183-.153.001-.001c.172-.143.324-.27.47-.412.368-.355.569-.676.569-1.136a.95.95 0 0 0-.404-.806C12.766 8.118 12.384 8 12 8c-.494 0-.814.121-1.03.265M13 17a1 1 0 1 1-2 0 1 1 0 0 1 2 0"/><path d="M12 1c6.075 0 1Line truncated
@@ -1,6 +1,6 @@
 # JSON for Modern C++

-JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, `json.hpp`, with no dependencies, no subproject, and no complex build system to set up; a companion header, `json_fwd.hpp`, provides forward declarations to keep compile times down. See [header-only integration](https://json.nlohmann.me/integration/index.md) for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.
+JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, `json.hpp`, with no dependencies, no subproject, and no complex build system to set up; a companion header, `json_fwd.hpp`, provides forward declarations to keep compile times down, `<nlohmann/json_literals.hpp>` holds the user-defined string literals on their own, and `<nlohmann/json_view.hpp>` adds zero-copy views and editable documents. See [header-only integration](https://json.nlohmann.me/integration/index.md) for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.

 ## Quick start

@@ -46,7 +46,7 @@ See [Integration](https://json.nlohmann.me/integration/index.md) for CMake in de

  ______________________________________________________________________

-  Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.
+  Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, zero-copy views, and more.

  [Features](https://json.nlohmann.me/features/index.md)

@@ -62,7 +62,7 @@ See [Integration](https://json.nlohmann.me/integration/index.md) for CMake in de

  ______________________________________________________________________

-  The complete reference for `basic_json` and its member functions, types, and related classes.
+  The complete reference for `basic_json` and its member functions, types, and related classes, as well as for `json_document` and `json_view`.

  [API documentation](https://json.nlohmann.me/api/basic_json/index.md)

@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;nlohmann/json.hpp&gt;\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // parse a JSON string\n    json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n    // access and modify values\n    j[\"name\"] = \"Niels\";\n    j[\"list\"] = {1, 0, 2};\n\n    // serialize with an indent of 4 spaces\n    std::cout &lt;&lt; j.dump(4) &lt;&lt; '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json    # Homebrew\nvcpkg install nlohmann-json   # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json&lt;&gt;;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;iomanip&gt;\n#include &lt;nlohmann/json.hpp&gt;\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j =\n    {\n        {\"pi\", 3.141},\n        {\"happy\", true},\n        {\"name\", \"Niels\"},\n        {\"nothing\", nullptr},\n        {\n            \"answer\", {\n                {\"everything\", 42}\n            }\n        },\n        {\"list\", {1, 0, 2}},\n        {\n            \"object\", {\n                {\"currency\", \"USD\"},\n                {\"value\", 42.99}\n            }\n        }\n    };\n\n    // add new values\n    j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n    // count elements\n    auto s = j.size();\n    j[\"size\"] = s;\n\n    // pretty print with indent of 4 spaces\n    std::cout &lt;&lt; std::setw(4) &lt;&lt; j &lt;&lt; '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>{\n    \"answer\": {\n        \"everything\": 42\n    },\n    \"happy\": true,\n    \"list\": [\n        1,\n        0,\n        2\n    ],\n    \"name\": \"Niels\",\n    \"new\": {\n        \"key\": {\n            \"value\": [\n                \"another\",\n    Line truncated
+{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down, <code>&lt;nlohmann/json_literals.hpp&gt;</code> holds the user-defined string literals on their own, and <code>&lt;nlohmann/json_view.hpp&gt;</code> adds zero-copy views and editable documents. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;nlohmann/json.hpp&gt;\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // parse a JSON string\n    json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n    // access and modify values\n    j[\"name\"] = \"Niels\";\n    j[\"list\"] = {1, 0, 2};\n\n    // serialize with an indent of 4 spaces\n    std::cout &lt;&lt; j.dump(4) &lt;&lt; '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json    # Homebrew\nvcpkg install nlohmann-json   # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, zero-copy views, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes, as well as for <code>json_document</code> and <code>json_view</code>.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json&lt;&gt;;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;iomanip&gt;\n#include &lt;nlohmann/json.hpp&gt;\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j =\n    {\n        {\"pi\", 3.141},\n        {\"happy\", true},\n        {\"name\", \"Niels\"},\n        {\"nothing\", nullptr},\n        {\n            \"answer\", {\n                {\"everything\", 42}\n            }\n        },\n        {\"list\", {1, 0, 2}},\n        {\n            \"object\", {\n                {\"currency\", \"USD\"},\n                {\"value\", 42.99}\n            }\n        }\n    };\n\n    // add new values\n    j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n    // count elements\n    auto s = j.size();\n    j[\"size\"] = s;\n\n    // pretty print with indent of 4 spaces\n    std::cout &lt;&lt; std::setw(4) &lt;&lt; j &lt;&lt; '\\n';\n}\n</code></pre> <p>OutpLine truncated