deploy: 54f6b3ef06

2026-10-29 12:40:52 +00:00 · 2026-10-28 20:27:06 +00:00
1 parent 11a863958e
commit 40c9f42917
@@ -90,7 +90,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
+   constant for an array.

 ## Notes

@@ -15,7 +15,7 @@
 <span class=c1>// (4)</span>
 <span class=n>reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&amp;</span><span class=w> </span><span class=n>ptr</span><span class=p>);</span>
 <span class=n>const_reference</span><span class=w> </span><span class=nf>at</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&amp;</span><span class=w> </span><span class=n>ptr</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
-</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>, with bounds checking.</li> <li>Returns a reference to the object element with specified key <code>key</code>, with bounds checking.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element at specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>, with bounds checking.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the elements to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>reference to the element at index <code>idx</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array; in this case, calling <code>at</code> with an index makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if the index <code>idx</code> is out of range of the array; that is, <code>idx &gt;= size()</code>. See the example below.</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in this case, calling <code>at</code> with a key makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the key <code>key</code> is not stored in the object; that is, <code>find(key) == end()</code>. See the example below.</li> </ul> </li> <li>See 2.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is out of range. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index '-' is used in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>. As <code>at</code> provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer describes a keLine truncated
+</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>, with bounds checking.</li> <li>Returns a reference to the object element with specified key <code>key</code>, with bounds checking.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element at specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>, with bounds checking.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the elements to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>reference to the element at index <code>idx</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element at key <code>key</code></li> <li>reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array; in this case, calling <code>at</code> with an index makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if the index <code>idx</code> is out of range of the array; that is, <code>idx &gt;= size()</code>. See the example below.</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error304><code>type_error.304</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in this case, calling <code>at</code> with a key makes no sense. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the key <code>key</code> is not stored in the object; that is, <code>find(key) == end()</code>. See the example below.</li> </ul> </li> <li>See 2.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is out of range. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index '-' is used in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>. As <code>at</code> provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> pointer describes a keLine 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>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
@@ -498,4 +498,4 @@
 <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>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>402</span><span class=p>]</span><span class=w> </span><span class=err>array</span><span class=w> </span><span class=err>i</span><span class=kc>n</span><span class=err>dex</span><span class=w> </span><span class=err>'</span><span class=mi>-</span><span class=err>'</span><span class=w> </span><span class=err>(</span><span class=mi>2</span><span class=err>)</span><span class=w> </span><span class=err>is</span><span class=w> </span><span class=err>ou</span><span class=kc>t</span><span class=w> </span><span class=err>o</span><span class=kc>f</span><span class=w> </span><span class=err>ra</span><span class=kc>n</span><span class=err>ge</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>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>403</span><span class=p>]</span><span class=w> </span><span class=err>key</span><span class=w> </span><span class=err>'</span><span class=kc>f</span><span class=err>oo'</span><span class=w> </span><span class=kc>n</span><span class=err>o</span><span class=kc>t</span><span class=w> </span><span class=kc>f</span><span class=err>ou</span><span class=kc>n</span><span class=err>d</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>.ou</span><span class=kc>t</span><span class=err>_o</span><span class=kc>f</span><span class=err>_ra</span><span class=kc>n</span><span class=err>ge.</span><span class=mi>404</span><span class=p>]</span><span class=w> </span><span class=err>u</span><span class=kc>nres</span><span class=err>olved</span><span class=w> </span><span class=err>re</span><span class=kc>feren</span><span class=err>ce</span><span class=w> </span><span class=kc>t</span><span class=err>oke</span><span class=kc>n</span><span class=w> </span><span class=err>'</span><span class=kc>f</span><span class=err>oo'</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=../../../features/element_access/checked_access/ >Checked access</a> - element access with range checking</li> <li><a href=../operator%5B%5D/ ><code>operator[]</code></a> - unchecked access by reference</li> <li><a href=../value/ ><code>value</code></a> - access with default value</li> <li><a href=../../basic_json_view/at/ ><code>basic_json_view::at</code></a> - the same access on a zero-copy view</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - access nested values with a pointer</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</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>, consistently across the lookup functions.</li> <li>Added in version 2.0.0. Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../as_base_class/ class="md-footer__link md-footer__link--prev" aria-label="Previous: as_base_class"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> as_base_class </div> </div> </a> <a href=../back/ class="md-footer__link md-footer__link--next" aria-label="Next: back"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> back </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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-2sLine 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=../../../features/element_access/checked_access/ >Checked access</a> - element access with range checking</li> <li><a href=../operator%5B%5D/ ><code>operator[]</code></a> - unchecked access by reference</li> <li><a href=../value/ ><code>value</code></a> - access with default value</li> <li><a href=../../basic_json_view/at/ ><code>basic_json_view::at</code></a> - the same access on a zero-copy view</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - access nested values with a pointer</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 1.0.0.</li> <li>Added in version 1.0.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</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>, consistently across the lookup functions.</li> <li>Added in version 2.0.0. Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 16:15:55 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../as_base_class/ class="md-footer__link md-footer__link--prev" aria-label="Previous: as_base_class"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> as_base_class </div> </div> </a> <a href=../back/ class="md-footer__link md-footer__link--next" aria-label="Next: back"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> back </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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-2sLine truncated
@@ -71,7 +71,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 1. Logarithmic in the size of the container.
 1. Logarithmic in the size of the container.
-1. Logarithmic in the size of the container.
+1. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or constant for an array.

 ## Notes

@@ -19,9 +19,10 @@ The equality holds up to [`operator==`](operator_eq.md), so it has the following
 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
  to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
  serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`,
-  `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then
-  the `source` and keeps its number type.
+- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is
+  negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and
+  `diff(0.0, -0.0)` (positive and negative zero) all return `#!json []`. The patched value is then the `source` and
+  keeps its number type and sign.

 ## Parameters

@@ -2,7 +2,7 @@
 <span class=w>                       </span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>target</span><span class=p>,</span>
 <span class=w>                       </span><span class=k>const</span><span class=w> </span><span class=n>string_t</span><span class=o>&amp;</span><span class=w> </span><span class=n>path</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>""</span><span class=p>);</span>
 </code></pre></div> <p>Creates a <a href="http://jsonpatch.com"><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a> so that value <code>source</code> can be changed into the value <code>target</code> by calling <a href=../patch/ ><code>patch</code></a> function.</p> <p>For two <abbr title="JavaScript Object Notation">JSON</abbr> values <code>source</code> and <code>target</code>, the following code yields <code class=highlight><span class=nb>true</span></code>: <div class=highlight><pre><span></span><code><span class=n>source</span><span class=p>.</span><span class=n>patch</span><span class=p>(</span><span class=n>diff</span><span class=p>(</span><span class=n>source</span><span class=p>,</span><span class=w> </span><span class=n>target</span><span class=p>))</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>target</span><span class=p>;</span>
-</code></pre></div></p> <p>The equality holds up to <a href=../operator_eq/ ><code>operator==</code></a>, so it has the following exceptions:</p> <ul> <li>A value that is not equal to itself cannot round-trip. This applies to <code>NaN</code> (also nested in an array or object) and to <a href=../is_discarded/ >discarded</a> values: <code>diff</code> emits a <code>replace</code> operation for them. A <code>NaN</code> in the patch is serialized as <code class=highlight><span class=kc>null</span></code>, so a patch that was dumped and parsed again would set <code class=highlight><span class=kc>null</span></code>.</li> <li>Numbers that compare equal produce no operation, even if their types or signs differ: <code>diff(1, 1.0)</code>, <code>diff(1u, 1)</code> (unsigned and signed integer) and <code>diff(0.0, -0.0)</code> all return <code class=highlight><span class=p>[]</span></code>. The patched value is then the <code>source</code> and keeps its number type.</li> </ul> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>source</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare from</dd> <dt><code>target</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare against</dd> <dt><code>path</code> (in)</dt> <dd>a prefix that is put verbatim in front of the <code>path</code> member of every operation (default: <code>""</code>, which addresses the root of the value). The prefix is neither escaped nor validated: <code class=highlight><span class=n>diff</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=s>"abc"</span><span class=p>)</span></code> yields an operation with the <code>path</code> <code>abc</code>, which is not a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer. Use it with a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer such as <code>/root</code> and escape <code>~</code> and <code>/</code> in its reference tokens (see <a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a>).</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>a <abbr title="JavaScript Object Notation">JSON</abbr> patch to convert the <code>source</code> to <code>target</code></p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: <code>source</code> and <code>target</code> are never modified.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the total number of values (including nested ones) in <code>source</code> and <code>target</code>, times the cost of a key-based object operation (looking up a key in an object): logarithmic for <a href=../../json/ ><code>json</code></a>, and linear for <a href=../../ordered_json/ ><code>ordered_json</code></a> (see <a href=../../ordered_map/#complexity><code>ordered_map</code> complexity</a>). For <code>ordered_json</code>, diffing two objects with <code>n</code> and <code>m</code> members therefore takes O((n+m)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long <code>path</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <ul> <li>Currently, only <code>remove</code>, <code>add</code>, and <code>replace</code> operations are generated.</li> <li>The patch is correct, but not guaranteed to be minimal. For instance, <code>diff([1,2,3], [0,1,2,3])</code> yields three <code>replace</code> operations and one <code>add</code> operation instead of a single insertion.</li> <li>Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with <code>add</code> operations on the path <code>/-</code> (appended in order), and elements that were removed are removed with <code>remove</code> operations from the highest index down to the lowest, so that the remaining indices stay valid.</li> <li>For objects, the operations for the members of <code>source</code> come first (<code>replace</code>, <code>remove</code>, or the operations for nested values, in the iteration order of <code>source</code>), followed by <code>add</code> operations for the members that only <code>target</code> has.</li> <li>For <a href=../../ordered_json/ ><code>ordered_json</code></a>, objects with the same keys in a different order are different. As a patch cannot reorder members, <code>diff</code> removes all keys of the <code>source</code> object and adds them agaLine truncated
+</code></pre></div></p> <p>The equality holds up to <a href=../operator_eq/ ><code>operator==</code></a>, so it has the following exceptions:</p> <ul> <li>A value that is not equal to itself cannot round-trip. This applies to <code>NaN</code> (also nested in an array or object) and to <a href=../is_discarded/ >discarded</a> values: <code>diff</code> emits a <code>replace</code> operation for them. A <code>NaN</code> in the patch is serialized as <code class=highlight><span class=kc>null</span></code>, so a patch that was dumped and parsed again would set <code class=highlight><span class=kc>null</span></code>.</li> <li>Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is negative zero: <code>diff(1, 1.0)</code> (integer and floating-point), <code>diff(1u, 1)</code> (unsigned and signed integer) and <code>diff(0.0, -0.0)</code> (positive and negative zero) all return <code class=highlight><span class=p>[]</span></code>. The patched value is then the <code>source</code> and keeps its number type and sign.</li> </ul> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>source</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare from</dd> <dt><code>target</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> value to compare against</dd> <dt><code>path</code> (in)</dt> <dd>a prefix that is put verbatim in front of the <code>path</code> member of every operation (default: <code>""</code>, which addresses the root of the value). The prefix is neither escaped nor validated: <code class=highlight><span class=n>diff</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=s>"abc"</span><span class=p>)</span></code> yields an operation with the <code>path</code> <code>abc</code>, which is not a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer. Use it with a valid <abbr title="JavaScript Object Notation">JSON</abbr> Pointer such as <code>/root</code> and escape <code>~</code> and <code>/</code> in its reference tokens (see <a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a>).</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>a <abbr title="JavaScript Object Notation">JSON</abbr> patch to convert the <code>source</code> to <code>target</code></p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: <code>source</code> and <code>target</code> are never modified.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the total number of values (including nested ones) in <code>source</code> and <code>target</code>, times the cost of a key-based object operation (looking up a key in an object): logarithmic for <a href=../../json/ ><code>json</code></a>, and linear for <a href=../../ordered_json/ ><code>ordered_json</code></a> (see <a href=../../ordered_map/#complexity><code>ordered_map</code> complexity</a>). For <code>ordered_json</code>, diffing two objects with <code>n</code> and <code>m</code> members therefore takes O((n+m)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long <code>path</code>.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <ul> <li>Currently, only <code>remove</code>, <code>add</code>, and <code>replace</code> operations are generated.</li> <li>The patch is correct, but not guaranteed to be minimal. For instance, <code>diff([1,2,3], [0,1,2,3])</code> yields three <code>replace</code> operations and one <code>add</code> operation instead of a single insertion.</li> <li>Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with <code>add</code> operations on the path <code>/-</code> (appended in order), and elements that were removed are removed with <code>remove</code> operations from the highest index down to the lowest, so that the remaining indices stay valid.</li> <li>For objects, the operations for the members of <code>source</code> come first (<code>replace</code>, <code>remove</code>, or the operations for nested values, in the iteration order of <code>source</code>), followed by <code>add</code> operations for the members that only <code>target</code> has.</li> <li>For <a href=../../ordered_json/ ><code>ordered_json</code></a>, objects with the same keys in a different order are different. As a patch canLine 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>

@@ -64,4 +64,4 @@
 <span class=w>        </span><span class=s2>"world"</span>
 <span class=w>    </span><span class=p>]</span>
 <span class=p>}</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href="https://tools.ietf.org/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch/ ><code>patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch_inplace/ ><code>patch_inplace</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch in place</li> <li><a href=../merge_patch/ ><code>merge_patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../merge_diff/ ><code>merge_diff</code></a> - creates a diff as a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Patch</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 2.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 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../default_object_comparator_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: default_object_comparator_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> default_object_comparator_t </div> </div> </a> <a href=../dump/ class="md-footer__link md-footer__link--next" aria-label="Next: dump"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> dump </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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 2Line 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/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch/ ><code>patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../patch_inplace/ ><code>patch_inplace</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch in place</li> <li><a href=../merge_patch/ ><code>merge_patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../merge_diff/ ><code>merge_diff</code></a> - creates a diff as a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Patch</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 2.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 27, 2026 16:16:08 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../default_object_comparator_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: default_object_comparator_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> default_object_comparator_t </div> </div> </a> <a href=../dump/ class="md-footer__link md-footer__link--next" aria-label="Next: dump"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> dump </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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 2Line truncated
@@ -17,7 +17,7 @@ source.patch(diff(source, target)) == target;
 The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), so it has the following exceptions:

 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and to [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is serialized as `null`, so a patch that was dumped and parsed again would set `null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`, `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `[]`. The patched value is then the `source` and keeps its number type.
+- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` (positive and negative zero) all return `[]`. The patched value is then the `source` and keeps its number type and sign.

 ## Parameters

@@ -92,12 +92,20 @@ Strong exception safety: if an exception occurs, the original value stays intact
    For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an
    exception, but is undefined behavior (see the notes below). Use [`at`](at.md) for checked access.

+    If the **non-const** version throws, the value is left unchanged: values it created for earlier reference tokens
+    of `ptr` are removed again. This also holds for exceptions such as `#!cpp std::bad_alloc` or
+    `#!cpp std::length_error` thrown while padding an array up to a very large index. With custom
+    [template parameters](../../features/types/template_parameters.md), this requires that `erase()` of the object and
+    array types and the move operations of the custom base class do not throw.
+
 ## Complexity

 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
+   constant for an array. When the non-const version pads an array with `#!json null` values, it is additionally
+   linear in `idx - size()` for that array.

 ## Notes

@@ -145,6 +153,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
        specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also
        [JSON Pointer](../../features/json_pointer.md).

+    !!! warning "Large array indices"
+
+        As the array is filled up with `#!json null` values to the given index, the memory used grows with the index
+        and not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB.
+        The library does not limit the index, so check the array indices of a JSON pointer from untrusted input
+        before using it with the non-const version. See
+        [Parsing untrusted input](../../features/parsing/untrusted_input.md#json-pointers-and-flattened-keys).
+
 !!! warning "Deprecation"

    Overload (4) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json`
@@ -564,4 +580,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
 4. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since
   version 3.13.0. Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
 [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is not
-a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
+a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones. Fixed in version 3.13.0 to leave the value
+unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier
+reference tokens of `ptr` were kept.
@@ -15,7 +15,7 @@
 <span class=c1>// (4)</span>
 <span class=n>reference</span><span class=w> </span><span class=k>operator</span><span class=p>[](</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&amp;</span><span class=w> </span><span class=n>ptr</span><span class=p>);</span>
 <span class=n>const_reference</span><span class=w> </span><span class=k>operator</span><span class=p>[](</span><span class=k>const</span><span class=w> </span><span class=n>json_pointer</span><span class=o>&amp;</span><span class=w> </span><span class=n>ptr</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
-</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>.</li> <li>Returns a reference to the object element with specified key <code>key</code>. The non-const qualified overload takes the key by value.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element with specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">&para;</a></h2> <p>For the non-const versions 1. and 4., when passing an <strong>array</strong> index that does not exist, it is created and filled with a <code class=highlight><span class=kc>null</span></code> value before a reference to it is returned. For this, a reallocation can happen, 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 passing an <strong>object key</strong> to the non-const versions 2., 3., and 4., a reallocation can happen which again invalidates all iterators and all references.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the element to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>(const) reference to the element at index <code>idx</code></li> <li>(const) reference to the element at key <code>key</code></li> <li>(const) reference to the element at key <code>key</code></li> <li>(const) reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error305><code>type_error.305</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array or null; in that case, using the <code>[]</code> operator with an index makes no sense.</li> <li>Throws <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>length_error</span></code> if <code>idx</code> equals the maximum value of <code>size_type</code>; the array is left unchanged. (This is the one index for which growing the array to hold it cannot be expressed as a <code>size_type</code> size, the same way an oversized <a href="https://en.cppreference.com/w/cpp/container/vector/resize"><code>resize</code></a> throws.)</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error305><code>type_error.305</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object or null; in that case, using the <code>[]</code> operator with a key makes no sense.</li> </ul> </li> <li>See 2.</li> <li> <p>The function can throw the following exceptions:</p> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number.</li> <li>Throws <a href=../../../home/exceptions/#jsonexLine truncated
+</code></pre></div> <ol> <li>Returns a reference to the array element at specified location <code>idx</code>.</li> <li>Returns a reference to the object element with specified key <code>key</code>. The non-const qualified overload takes the key by value.</li> <li>See 2. This overload is only available if <code>KeyType</code> is comparable with <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_t</span><span class=o>::</span><span class=n>key_type</span></code> and <code class=highlight><span class=k>typename</span><span class=w> </span><span class=nc>object_comparator_t</span><span class=o>::</span><span class=n>is_transparent</span></code> denotes a type.</li> <li>Returns a reference to the element with specified <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code>.</li> </ol> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>KeyType</code></dt> <dd>A type for an object key other than <a href=../../json_pointer/ ><code>json_pointer</code></a> that is comparable with <a href=../string_t/ ><code>string_t</code></a> using <a href=../object_comparator_t/ ><code>object_comparator_t</code></a>. This can also be a string view (C++17).</dd> </dl> <h2 id=iterator-invalidation>Iterator invalidation<a class=headerlink href=#iterator-invalidation title="Permanent link">&para;</a></h2> <p>For the non-const versions 1. and 4., when passing an <strong>array</strong> index that does not exist, it is created and filled with a <code class=highlight><span class=kc>null</span></code> value before a reference to it is returned. For this, a reallocation can happen, 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 passing an <strong>object key</strong> to the non-const versions 2., 3., and 4., a reallocation can happen which again invalidates all iterators and all references.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>idx</code> (in)</dt> <dd>index of the element to access</dd> <dt><code>key</code> (in)</dt> <dd>object key of the element to access</dd> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to the desired element</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>(const) reference to the element at index <code>idx</code></li> <li>(const) reference to the element at key <code>key</code></li> <li>(const) reference to the element at key <code>key</code></li> <li>(const) reference to the element pointed to by <code>ptr</code></li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong exception safety: if an exception occurs, the original value stays intact.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ol> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error305><code>type_error.305</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an array or null; in that case, using the <code>[]</code> operator with an index makes no sense.</li> <li>Throws <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>length_error</span></code> if <code>idx</code> equals the maximum value of <code>size_type</code>; the array is left unchanged. (This is the one index for which growing the array to hold it cannot be expressed as a <code>size_type</code> size, the same way an oversized <a href="https://en.cppreference.com/w/cpp/container/vector/resize"><code>resize</code></a> throws.)</li> </ul> </li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error305><code>type_error.305</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object or null; in that case, using the <code>[]</code> operator with a key makes no sense.</li> </ul> </li> <li>See 2.</li> <li> <p>The function can throw the following exceptions:</p> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> begins with '0'.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in the passed <abbr title="JavaScript Object Notation">JSON</abbr> pointer <code>ptr</code> is not a number.</li> <li>Throws <a href=../../../home/exceptions/#jsonexLine 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>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
@@ -283,4 +283,4 @@
 <span class=s2>"foo"</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>2</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=../../../features/element_access/unchecked_access/ >Unchecked access</a> - element access without range checking</li> <li><a href=../../../features/assertions/ >Runtime assertions</a> - assertions guarding against undefined behavior</li> <li><a href=../at/ ><code>at</code></a> - access by reference with range checking</li> <li><a href=../value/ ><code>value</code></a> - access with default value</li> <li><a href=../../basic_json_view/operator%5B%5D/ ><code>basic_json_view::operator[]</code></a> - the same access on a zero-copy view (a duplicate key resolves to the first member, whereas <code>parse()</code> keeps the last; a missing key gives a discarded view instead of undefined behavior)</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - access nested values with a pointer</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 1.0.0. Fixed 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 throw <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>length_error</span></code> instead of emptying the array and accessing it out of bounds when <code>idx</code> equals the maximum value of <code>size_type</code>. A missing index in the const version is guarded by a runtime assertion since 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 in version 1.0.0. Added overloads for <code>T* key</code> in version 1.1.0. The <code>T* key</code> overloads forward to overload 3 since version 3.11.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</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>, consistently across the lookup functions.</li> <li>Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../operator_value_t/ class="md-footer__link md-footer__link--prev" aria-label="Previous: operator value_t"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__dLine 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=../../../features/element_access/unchecked_access/ >Unchecked access</a> - element access without range checking</li> <li><a href=../../../features/assertions/ >Runtime assertions</a> - assertions guarding against undefined behavior</li> <li><a href=../at/ ><code>at</code></a> - access by reference with range checking</li> <li><a href=../value/ ><code>value</code></a> - access with default value</li> <li><a href=../../basic_json_view/operator%5B%5D/ ><code>basic_json_view::operator[]</code></a> - the same access on a zero-copy view (a duplicate key resolves to the first member, whereas <code>parse()</code> keeps the last; a missing key gives a discarded view instead of undefined behavior)</li> <li><a href=../../../features/element_access/ >Element Access</a> - overview of all ways to access elements</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - access nested values with a pointer</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 1.0.0. Fixed 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 throw <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>length_error</span></code> instead of emptying the array and accessing it out of bounds when <code>idx</code> equals the maximum value of <code>size_type</code>. A missing index in the const version is guarded by a runtime assertion since 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 in version 1.0.0. Added overloads for <code>T* key</code> in version 1.1.0. The <code>T* key</code> overloads forward to overload 3 since version 3.11.0.</li> <li>Added in version 3.11.0. Support for keys convertible to <code>std::string_view</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>, consistently across the lookup functions.</li> <li>Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones. Fixed 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 leave the value unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier reference tokens of <code>ptr</code> were kept.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 16:15:55 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../operator_value_t/ cLine truncated
@@ -77,12 +77,14 @@ Strong exception safety: if an exception occurs, the original value stays intact

   For the **const** version, an object key or array index in `ptr` that does not exist is not reported by an exception, but is undefined behavior (see the notes below). Use [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) for checked access.

+   If the **non-const** version throws, the value is left unchanged: values it created for earlier reference tokens of `ptr` are removed again. This also holds for exceptions such as `std::bad_alloc` or `std::length_error` thrown while padding an array up to a very large index. With custom [template parameters](https://json.nlohmann.me/features/types/template_parameters/index.md), this requires that `erase()` of the object and array types and the move operations of the custom base class do not throw.
+
 ## Complexity

 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
 1. Logarithmic in the size of the container.
 1. Logarithmic in the size of the container.
-1. Logarithmic in the size of the container.
+1. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or constant for an array. When the non-const version pads an array with `null` values, it is additionally linear in `idx - size()` for that array.

 ## Notes

@@ -114,6 +116,10 @@ The following cases apply to the **const** overloads; the non-const overloads in

   When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing leaf), each missing level is created as an array or an object depending on whether the corresponding pointer token is a valid array index: the token `0`, a sequence of digits that does not begin with `0`, or the token `-` creates an array, and every other token creates an object. For example, on an initially `null` value, `/foo/0/0/0` creates nested arrays, while `/foo/one/one/one` creates nested objects. Tokens such as `01` or the empty token cannot be array indices (cf. RFC 6901, Sect. 4) and therefore create objects, just as they would if the level already existed as an object. This is not specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md).

+   Large array indices
+
+   As the array is filled up with `null` values to the given index, the memory used grows with the index and not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB. The library does not limit the index, so check the array indices of a JSON pointer from untrusted input before using it with the non-const version. See [Parsing untrusted input](https://json.nlohmann.me/features/parsing/untrusted_input/#json-pointers-and-flattened-keys).
+
 Deprecation

 Overload (4) also accepts a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead.
@@ -503,4 +509,4 @@ Output:
 1. Added in version 1.0.0. Fixed in version 3.13.0 unreleased to throw `std::length_error` instead of emptying the array and accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased.
 1. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. The `T* key` overloads forward to overload 3 since version 3.11.0.
 1. Added in version 3.11.0. Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
-1. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased. Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+1. Added in version 2.0.0. A missing array index in the const version is guarded by a runtime assertion since version 3.13.0 unreleased. Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones. Fixed in version 3.13.0 unreleased to leave the value unchanged if the non-const version throws (strong exception safety, as documented); before, values created for earlier reference tokens of `ptr` were kept.
@@ -69,6 +69,19 @@ Duplicate member names inside an operation object are resolved by the parser bef
 is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op": "remove", "path": "/a"}` is a
 `remove` operation.

+The JSON patch may be the JSON value itself (`#!cpp j.patch_inplace(j)`): the operations are then read from a copy of
+the patch made before the first operation is applied, so the result is the same as that of
+`#!cpp j = j.patch(j)`, and the exception safety is the same as above.
+
+If [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) is enabled, the same holds for a JSON patch stored inside the
+JSON value (e.g., `#!cpp j.patch_inplace(j["patch"])`): it is detected via the parent pointers.
+
+!!! danger "Undefined behavior"
+
+    Without [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md), the JSON patch must not be a value stored inside the
+    JSON value (e.g., `#!cpp j.patch_inplace(j["patch"])`), as the operations may change or destroy it while it is
+    read. Pass a copy (`#!cpp j.patch_inplace(json(j["patch"]))`) or use [`patch`](patch.md) instead.
+
 ## Examples

 ??? example "Example: apply a JSON patch in place"
@@ -213,3 +226,5 @@ is kept, see [`object_t`](object_t.md#behavior)), so `#!json {"op": "add", "op":
 - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) instead of
  [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) for a one-character array index that is
  not a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.
+- Applying a JSON value as patch to itself (or, with `JSON_DIAGNOSTICS`, to a value stored inside it) no longer results
+  in undefined behavior in version 3.13.0.
@@ -1,5 +1,5 @@
 <!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/patch_inplace/" rel="canonical"><link href=../patch/ rel=prev><link href=../push_back/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>patch_inplace - 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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonpatch_inplace class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> patch_inplace </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path dLine truncated
-</code></pre></div> <p><a href="http://jsonpatch.com"><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a> defines a <abbr title="JavaScript Object Notation">JSON</abbr> document structure for expressing a sequence of operations to apply to a <abbr title="JavaScript Object Notation">JSON</abbr> document. With this function, a <abbr title="JavaScript Object Notation">JSON</abbr> Patch is applied to the current <abbr title="JavaScript Object Notation">JSON</abbr> value by executing all operations from the patch. This function applies a <abbr title="JavaScript Object Notation">JSON</abbr> patch in place and returns void.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>json_patch</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> patch document</dd> </dl> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>No guarantees, value may be corrupted by an unsuccessful patch operation.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error104><code>parse_error.104</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> patch does not consist of an array of objects.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error105><code>parse_error.105</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> patch is malformed (e.g., mandatory attributes are missing); example: <code>"operation 'add' must have member 'path'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index is out of range.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in a "path" or "from" member begins with '0'; example: <code>"array index '01' must not begin with '0'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error107><code>parse_error.107</code></a> if a "path" or "from" member is not empty and does not begin with a slash (<code>/</code>); example: <code>"JSON pointer must be empty or begin with '/' - was: 'a'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error108><code>parse_error.108</code></a> if a tilde (<code>~</code>) in a "path" or "from" member is not followed by <code>0</code> or <code>1</code>; example: <code>"escape character '~' must be followed with '0' or '1'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in a "path" or "from" member is not a number; example: <code>"array index 'foo' is not a number"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index <code>-</code> is used where an existing element is required (the "path" of "replace", the "from" of "move" and "copy"); example: <code>"array index '-' (3) is out of range"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if a <abbr title="JavaScript Object Notation">JSON</abbr> pointer inside the patch could not be resolved successfully in the current <abbr title="JavaScript Object Notation">JSON</abbr> value; example: <code>"key 'baz' not found"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> if a reference token of a <abbr title="JavaScript Object Notation">JSON</abbr> pointer inside the patch cannot be resolved, e.g., <code>-</code> in a "remove" operation or <code>1a</code> for an array; example: <code>"unresolved reference token '-'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range405><code>out_of_range.405</code></a> if <abbr title="JavaScript Object Notation">JSON</abbr> pointer has no parent ("remove", "move")</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range411><code>out_of_range.411</code></a> if an "add" operation's target location has a parent that is neither an object nor an array.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range413><code>out_of_range.413</code></a> if a "remove" operation's target location has a parent that is neither an object nor an array.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range414><code>out_of_range.414</code></a> if a "move" operation's "from" location is a proper prefix of its "path" location.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionother_error501><code>other_error.501</code></a> if "test" operation was unsuccessful. A "test" operation whose "path" does not exist is unsuccessful, too: the failed lookup is reporLine truncated
+</code></pre></div> <p><a href="http://jsonpatch.com"><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a> defines a <abbr title="JavaScript Object Notation">JSON</abbr> document structure for expressing a sequence of operations to apply to a <abbr title="JavaScript Object Notation">JSON</abbr> document. With this function, a <abbr title="JavaScript Object Notation">JSON</abbr> Patch is applied to the current <abbr title="JavaScript Object Notation">JSON</abbr> value by executing all operations from the patch. This function applies a <abbr title="JavaScript Object Notation">JSON</abbr> patch in place and returns void.</p> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>json_patch</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> patch document</dd> </dl> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>No guarantees, value may be corrupted by an unsuccessful patch operation.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error104><code>parse_error.104</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> patch does not consist of an array of objects.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error105><code>parse_error.105</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> patch is malformed (e.g., mandatory attributes are missing); example: <code>"operation 'add' must have member 'path'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range401><code>out_of_range.401</code></a> if an array index is out of range.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error106><code>parse_error.106</code></a> if an array index in a "path" or "from" member begins with '0'; example: <code>"array index '01' must not begin with '0'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error107><code>parse_error.107</code></a> if a "path" or "from" member is not empty and does not begin with a slash (<code>/</code>); example: <code>"JSON pointer must be empty or begin with '/' - was: 'a'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error108><code>parse_error.108</code></a> if a tilde (<code>~</code>) in a "path" or "from" member is not followed by <code>0</code> or <code>1</code>; example: <code>"escape character '~' must be followed with '0' or '1'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> if an array index in a "path" or "from" member is not a number; example: <code>"array index 'foo' is not a number"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range402><code>out_of_range.402</code></a> if the array index <code>-</code> is used where an existing element is required (the "path" of "replace", the "from" of "move" and "copy"); example: <code>"array index '-' (3) is out of range"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range403><code>out_of_range.403</code></a> if a <abbr title="JavaScript Object Notation">JSON</abbr> pointer inside the patch could not be resolved successfully in the current <abbr title="JavaScript Object Notation">JSON</abbr> value; example: <code>"key 'baz' not found"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> if a reference token of a <abbr title="JavaScript Object Notation">JSON</abbr> pointer inside the patch cannot be resolved, e.g., <code>-</code> in a "remove" operation or <code>1a</code> for an array; example: <code>"unresolved reference token '-'"</code>.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range405><code>out_of_range.405</code></a> if <abbr title="JavaScript Object Notation">JSON</abbr> pointer has no parent ("remove", "move")</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range411><code>out_of_range.411</code></a> if an "add" operation's target location has a parent that is neither an object nor an array.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range413><code>out_of_range.413</code></a> if a "remove" operation's target location has a parent that is neither an object nor an array.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionout_of_range414><code>out_of_range.414</code></a> if a "move" operation's "from" location is a proper prefix of its "path" location.</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionother_error501><code>other_error.501</code></a> if "test" operation was unsuccessful. A "test" operation whose "path" does not exist is unsuccessful, too: the failed lookup is reporLine 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>

@@ -90,4 +90,4 @@
 <span class=w>    </span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=mi>99</span><span class=p>,</span>
 <span class=w>    </span><span class=nt>"b"</span><span class=p>:</span><span class=w> </span><span class=mi>2</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/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href="https://tools.ietf.org/html/rfc6901"><abbr title="Request for Comments">RFC</abbr> 6901 (<abbr title="JavaScript Object Notation">JSON</abbr> Pointer)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Pointer</li> <li><a href=../patch/ ><code>patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../merge_patch/ ><code>merge_patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Patch</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.11.0.</li> <li>Added <a href=../../../home/exceptions/#jsonexceptionout_of_range411><code>out_of_range.411</code></a> 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 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. This includes a <code>null</code> parent, which was previously silently converted to an object, 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 <a href=../../../home/exceptions/#jsonexceptionout_of_range413><code>out_of_range.413</code></a> and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent 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 <a href=../../../home/exceptions/#jsonexceptionout_of_range414><code>out_of_range.414</code></a> and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result 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>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones.</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../patch/ class="md-footer__link md-footer__link--prev" aria-label="Previous: patch"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span classLine 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/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902 (<abbr title="JavaScript Object Notation">JSON</abbr> Patch)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href="https://tools.ietf.org/html/rfc6901"><abbr title="Request for Comments">RFC</abbr> 6901 (<abbr title="JavaScript Object Notation">JSON</abbr> Pointer)</a> - specification of <abbr title="JavaScript Object Notation">JSON</abbr> Pointer</li> <li><a href=../patch/ ><code>patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Patch</li> <li><a href=../merge_patch/ ><code>merge_patch</code></a> - applies a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</li> <li><a href=../../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch and Diff</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Patch</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.11.0.</li> <li>Added <a href=../../../home/exceptions/#jsonexceptionout_of_range411><code>out_of_range.411</code></a> 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 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. This includes a <code>null</code> parent, which was previously silently converted to an object, 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 <a href=../../../home/exceptions/#jsonexceptionout_of_range413><code>out_of_range.413</code></a> and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent 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 <a href=../../../home/exceptions/#jsonexceptionout_of_range414><code>out_of_range.414</code></a> and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result 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>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of <a href=../../../home/exceptions/#jsonexceptionout_of_range404><code>out_of_range.404</code></a> for a one-character array index that is not a digit (e.g., <code>/x</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>, as it already did for longer ones.</li> <li>Applying a <abbr title="JavaScript Object Notation">JSON</abbr> value as patch to itself (or, with <code>JSON_DIAGNOSTICS</code>, to a value stored inside it) no longer results in undefined behavior 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 28, 2026 19:23:55 UTC">October 28, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-griLine truncated
@@ -42,6 +42,14 @@ Unlike [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md), `patch

 Duplicate member names inside an operation object are resolved by the parser before the patch is applied (the last one is kept, see [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/#behavior)), so `{"op": "add", "op": "remove", "path": "/a"}` is a `remove` operation.

+The JSON patch may be the JSON value itself (`j.patch_inplace(j)`): the operations are then read from a copy of the patch made before the first operation is applied, so the result is the same as that of `j = j.patch(j)`, and the exception safety is the same as above.
+
+If [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) is enabled, the same holds for a JSON patch stored inside the JSON value (e.g., `j.patch_inplace(j["patch"])`): it is detected via the parent pointers.
+
+Undefined behavior
+
+Without [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md), the JSON patch must not be a value stored inside the JSON value (e.g., `j.patch_inplace(j["patch"])`), as the operations may change or destroy it while it is read. Pass a copy (`j.patch_inplace(json(j["patch"]))`) or use [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) instead.
+
 ## Examples

 Example: apply a JSON patch in place
@@ -174,3 +182,4 @@ Output:
 - Added [`out_of_range.413`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range413) and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent in version 3.13.0 unreleased.
 - Added [`out_of_range.414`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range414) and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result in version 3.13.0 unreleased.
 - Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+- Applying a JSON value as patch to itself (or, with `JSON_DIAGNOSTICS`, to a value stored inside it) no longer results in undefined behavior in version 3.13.0 unreleased.
@@ -32,9 +32,24 @@ uses, so the result matches it exactly — including, for an object, that a repe
 last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion
 would be; the JSON nesting depth is limited only by available memory, as for `BasicJsonType::parse()` itself.

-Unlike parsing with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) enabled, the values
-produced by `materialize()` do not carry source positions. The index has the start offset of every value, but not the
-end of arrays, objects, and escaped strings, which the positions also need.
+With [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) enabled, the values get the source
+positions [`BasicJsonType::parse()`](../basic_json/parse.md) would give them, also for the subtree of a view (the
+positions are those in the document's whole source text), and exceptions about them name the same bytes. For values of
+an [editable document](../json_editable_document.md), positions are all-or-nothing, and [`start_pos()`](../basic_json/start_pos.md)
+and [`end_pos()`](../basic_json/end_pos.md) return `std::string::npos` for
+
+- a value written by an edit (a copy of an array or object of the document is also new; copies of its scalars keep
+  their positions),
+- an array or object whose elements were changed (its elements keep theirs), and
+- an array or object whose last element has no positions (its end is found from that element).
+
+This differs from a `basic_json` value, whose positions are not updated when it is changed: they stay as they were
+parsed, even if they no longer match the value (see [`start_pos()`](../basic_json/start_pos.md)).
+
+Documents [loaded](../basic_json_document/load.md) from an image have the positions of the saved document. Its strings
+with escapes have positions only if the document was parsed with `JSON_DIAGNOSTIC_POSITIONS`: the position of their
+opening quote is recorded while parsing, and `save()` and `load()` keep it whether or not they are compiled with the
+macro.

 Calling `materialize()` on the same view repeatedly builds a new, independent `BasicJsonType` value each time; it
 never caches the result.
@@ -98,8 +113,7 @@ never caches the result.

 - [`root`](../basic_json_document/root.md) - the view of a document's root value
 - [`BasicJsonType::parse`](../basic_json/parse.md) - build a `BasicJsonType` value directly from a JSON text
- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values (not
-  produced by `materialize()`)
+- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values
 - [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - when to build a basic_json value from a view

 ## Version history
@@ -1,5 +1,5 @@
 <!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json_view/materialize/" rel="canonical"><link href=../items/ rel=prev><link href=../number_format/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>materialize - 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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_json_viewmaterialize class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> materialize </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><Line truncated
-</code></pre></div> <p>Builds the <code>BasicJsonType</code> value of this subtree: the value <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> would have produced for the same source text, allocated for the first time by this call.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>The <code>BasicJsonType</code> value of this subtree, or a discarded <code>BasicJsonType</code> value (<code class=highlight><span class=n>BasicJsonType</span><span class=p>(</span><span class=n>value_t</span><span class=o>::</span><span class=n>discarded</span><span class=p>)</span></code>) if the view is <a href=../is_discarded/ >discarded</a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: there are no changes to the view or the document it refers to (nothing about either is mutated by this function).</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <p>May throw <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>bad_alloc</span></code> (via <code>BasicJsonType</code>'s allocator) if constructing the result fails.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the subtree.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <p><code>materialize()</code> replays the subtree through the same <abbr title="Simple API for XML">SAX</abbr> builder <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> uses, so the result matches it exactly — including, for an object, that a repeated key keeps only its last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion would be; the <abbr title="JavaScript Object Notation">JSON</abbr> nesting depth is limited only by available memory, as for <code>BasicJsonType::parse()</code> itself.</p> <p>Unlike parsing with <a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> enabled, the values produced by <code>materialize()</code> do not carry source positions. The index has the start offset of every value, but not the end of arrays, objects, and escaped strings, which the positions also need.</p> <p>Calling <code>materialize()</code> on the same view repeatedly builds a new, independent <code>BasicJsonType</code> value each time; it never caches the result.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example below skips messages that are not useful — a discarded value, or an empty array — using only <a href=../is_array/ ><code>is_array()</code></a> and <a href=../empty/ ><code>empty()</code></a>, and calls <code>materialize()</code> only for the messages that are actually used, so no <code>BasicJsonType</code> value (and none of its per-element allocations) is ever built for the skipped ones.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;array&gt;</span>
+</code></pre></div> <p>Builds the <code>BasicJsonType</code> value of this subtree: the value <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> would have produced for the same source text, allocated for the first time by this call.</p> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>The <code>BasicJsonType</code> value of this subtree, or a discarded <code>BasicJsonType</code> value (<code class=highlight><span class=n>BasicJsonType</span><span class=p>(</span><span class=n>value_t</span><span class=o>::</span><span class=n>discarded</span><span class=p>)</span></code>) if the view is <a href=../is_discarded/ >discarded</a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: there are no changes to the view or the document it refers to (nothing about either is mutated by this function).</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <p>May throw <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>bad_alloc</span></code> (via <code>BasicJsonType</code>'s allocator) if constructing the result fails.</p> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the subtree.</p> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <p><code>materialize()</code> replays the subtree through the same <abbr title="Simple API for XML">SAX</abbr> builder <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> uses, so the result matches it exactly — including, for an object, that a repeated key keeps only its last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion would be; the <abbr title="JavaScript Object Notation">JSON</abbr> nesting depth is limited only by available memory, as for <code>BasicJsonType::parse()</code> itself.</p> <p>With <a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> enabled, the values get the source positions <a href=../../basic_json/parse/ ><code>BasicJsonType::parse()</code></a> would give them, also for the subtree of a view (the positions are those in the document's whole source text), and exceptions about them name the same bytes. For values of an <a href=../../json_editable_document/ >editable document</a>, positions are all-or-nothing, and <a href=../../basic_json/start_pos/ ><code>start_pos()</code></a> and <a href=../../basic_json/end_pos/ ><code>end_pos()</code></a> return <code>std::string::npos</code> for</p> <ul> <li>a value written by an edit (a copy of an array or object of the document is also new; copies of its scalars keep their positions),</li> <li>an array or object whose elements were changed (its elements keep theirs), and</li> <li>an array or object whose last element has no positions (its end is found from that element).</li> </ul> <p>This differs from a <code>basic_json</code> value, whose positions are not updated when it is changed: they stay as they were parsed, even if they no longer match the value (see <a href=../../basic_json/start_pos/ ><code>start_pos()</code></a>).</p> <p>Documents <a href=../../basic_json_document/load/ >loaded</a> from an image have the positions of the saved document. Its strings with escapes have positions only if the document was parsed with <code>JSON_DIAGNOSTIC_POSITIONS</code>: the position of their opening quote is recorded while parsing, and <code>save()</code> and <code>load()</code> keep it whether or not they are compiled with the macro.</p> <p>Calling <code>materialize()</code> on the same view repeatedly builds a new, independent <code>BasicJsonType</code> value each time; it never caches the result.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example below skips messages that are not useful — a discarded value, or an empty array — using only <a href=../is_array/ ><code>is_array()</code></a> and <a href=../empty/ ><code>empty()</code></a>, and calls <code>materialize()</code> only for the messages that are actually used, so no <code>BasicJsonType</code> value (and none of its per-element allocations) is ever built for the skipped ones.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;array&gt;</span>
 <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_view.hpp&gt;</span>

@@ -35,4 +35,4 @@
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=err>skipped</span>
 <span class=err>skipped</span>
 <span class=p>[{</span><span class=nt>"id"</span><span class=p>:</span><span class=mi>1</span><span class=p>},{</span><span class=nt>"id"</span><span class=p>:</span><span class=mi>2</span><span class=p>},{</span><span class=nt>"id"</span><span class=p>:</span><span class=mi>3</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=../../basic_json_document/root/ ><code>root</code></a> - the view of a document's root value</li> <li><a href=../../basic_json/parse/ ><code>BasicJsonType::parse</code></a> - build a <code>BasicJsonType</code> value directly from a <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> - source positions on parsed values (not produced by <code>materialize()</code>)</li> <li><a href=../../../features/json_view/#getting-values-out-without-copying>Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - when to build a basic_json value from a view</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 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../items/ class="md-footer__link md-footer__link--prev" aria-label="Previous: items"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> items </div> </div> </a> <a href=../number_format/ class="md-footer__link md-footer__link--next" aria-label="Next: number_format"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> number_format </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.7Line 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=../../basic_json_document/root/ ><code>root</code></a> - the view of a document's root value</li> <li><a href=../../basic_json/parse/ ><code>BasicJsonType::parse</code></a> - build a <code>BasicJsonType</code> value directly from a <abbr title="JavaScript Object Notation">JSON</abbr> text</li> <li><a href=../../macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> - source positions on parsed values</li> <li><a href=../../../features/json_view/#getting-values-out-without-copying>Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - when to build a basic_json value from a view</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 28, 2026 19:24:49 UTC">October 28, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../items/ class="md-footer__link md-footer__link--prev" aria-label="Previous: items"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> items </div> </div> </a> <a href=../number_format/ class="md-footer__link md-footer__link--next" aria-label="Next: number_format"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> number_format </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.1C436Line truncated
@@ -26,7 +26,15 @@ Linear in the size of the subtree.

 `materialize()` replays the subtree through the same SAX builder [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) uses, so the result matches it exactly — including, for an object, that a repeated key keeps only its last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion would be; the JSON nesting depth is limited only by available memory, as for `BasicJsonType::parse()` itself.

-Unlike parsing with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) enabled, the values produced by `materialize()` do not carry source positions. The index has the start offset of every value, but not the end of arrays, objects, and escaped strings, which the positions also need.
+With [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) enabled, the values get the source positions [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would give them, also for the subtree of a view (the positions are those in the document's whole source text), and exceptions about them name the same bytes. For values of an [editable document](https://json.nlohmann.me/api/json_editable_document/index.md), positions are all-or-nothing, and [`start_pos()`](https://json.nlohmann.me/api/basic_json/start_pos/index.md) and [`end_pos()`](https://json.nlohmann.me/api/basic_json/end_pos/index.md) return `std::string::npos` for
+
+- a value written by an edit (a copy of an array or object of the document is also new; copies of its scalars keep their positions),
+- an array or object whose elements were changed (its elements keep theirs), and
+- an array or object whose last element has no positions (its end is found from that element).
+
+This differs from a `basic_json` value, whose positions are not updated when it is changed: they stay as they were parsed, even if they no longer match the value (see [`start_pos()`](https://json.nlohmann.me/api/basic_json/start_pos/index.md)).
+
+Documents [loaded](https://json.nlohmann.me/api/basic_json_document/load/index.md) from an image have the positions of the saved document. Its strings with escapes have positions only if the document was parsed with `JSON_DIAGNOSTIC_POSITIONS`: the position of their opening quote is recorded while parsing, and `save()` and `load()` keep it whether or not they are compiled with the macro.

 Calling `materialize()` on the same view repeatedly builds a new, independent `BasicJsonType` value each time; it never caches the result.

@@ -84,7 +92,7 @@ skipped

 - [`root`](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of a document's root value
 - [`BasicJsonType::parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) - build a `BasicJsonType` value directly from a JSON text
- [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) - source positions on parsed values (not produced by `materialize()`)
+- [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) - source positions on parsed values
 - [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/#getting-values-out-without-copying) - when to build a basic_json value from a view

 ## Version history
@@ -18,7 +18,8 @@ json_pointer& operator/=(std::size_t array_idx)
 ## Parameters

 `ptr` (in)
-:    JSON pointer to append
+:    JSON pointer to append; may be the JSON pointer itself (`#!cpp p /= p`), which then appends a copy of its
+     reference tokens

 `token` (in)
 :    reference token to append
@@ -96,6 +97,7 @@ json_pointer& operator/=(std::size_t array_idx)

 ## Version history

-1. Added in version 3.6.0.
+1. Added in version 3.6.0. Appending a JSON pointer to itself no longer results in undefined behavior in version
+   3.13.0.
 2. Added in version 3.6.0. Changed type of `token` to `string_t` in version 3.11.0.
 3. Added in version 3.6.0.
@@ -6,7 +6,7 @@

 <span class=c1>// (3)</span>
 <span class=n>json_pointer</span><span class=o>&amp;</span><span class=w> </span><span class=k>operator</span><span class=o>/=</span><span class=p>(</span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=n>array_idx</span><span class=p>)</span>
-</code></pre></div> <ol> <li>append another <abbr title="JavaScript Object Notation">JSON</abbr> pointer at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> <li>append an unescaped reference token at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> <li>append an array index at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> </ol> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to append</dd> <dt><code>token</code> (in)</dt> <dd>reference token to append</dd> <dt><code>array_idx</code> (in)</dt> <dd>array index to append</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>ptr</code> appended</li> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>token</code> appended without escaping <code>token</code></li> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>array_idx</code> appended</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <ol> <li>Basic guarantee: if an exception is thrown (for instance, if copying a reference token fails), the <abbr title="JavaScript Object Notation">JSON</abbr> pointer is left in a valid state, but it may contain some of the reference tokens of <code>ptr</code>.</li> <li>Strong guarantee: if an exception is thrown, there are no changes to the <abbr title="JavaScript Object Notation">JSON</abbr> pointer.</li> <li>Strong guarantee: if an exception is thrown, there are no changes to the <abbr title="JavaScript Object Notation">JSON</abbr> pointer.</li> </ol> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <ol> <li>Linear in the length of <code>ptr</code>.</li> <li>Amortized constant.</li> <li>Amortized constant.</li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the usage of <code>operator/=</code>.</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> <ol> <li>append another <abbr title="JavaScript Object Notation">JSON</abbr> pointer at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> <li>append an unescaped reference token at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> <li>append an array index at the end of this <abbr title="JavaScript Object Notation">JSON</abbr> pointer</li> </ol> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>ptr</code> (in)</dt> <dd><abbr title="JavaScript Object Notation">JSON</abbr> pointer to append; may be the <abbr title="JavaScript Object Notation">JSON</abbr> pointer itself (<code class=highlight><span class=n>p</span><span class=w> </span><span class=o>/=</span><span class=w> </span><span class=n>p</span></code>), which then appends a copy of its reference tokens</dd> <dt><code>token</code> (in)</dt> <dd>reference token to append</dd> <dt><code>array_idx</code> (in)</dt> <dd>array index to append</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>ptr</code> appended</li> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>token</code> appended without escaping <code>token</code></li> <li><abbr title="JavaScript Object Notation">JSON</abbr> pointer with <code>array_idx</code> appended</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <ol> <li>Basic guarantee: if an exception is thrown (for instance, if copying a reference token fails), the <abbr title="JavaScript Object Notation">JSON</abbr> pointer is left in a valid state, but it may contain some of the reference tokens of <code>ptr</code>.</li> <li>Strong guarantee: if an exception is thrown, there are no changes to the <abbr title="JavaScript Object Notation">JSON</abbr> pointer.</li> <li>Strong guarantee: if an exception is thrown, there are no changes to the <abbr title="JavaScript Object Notation">JSON</abbr> pointer.</li> </ol> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <ol> <li>Linear in the length of <code>ptr</code>.</li> <li>Amortized constant.</li> <li>Amortized constant.</li> </ol> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the usage of <code>operator/=</code>.</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>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
@@ -33,4 +33,4 @@
 <span class=s2>"/foo/bar/baz"</span>
 <span class=s2>"/foo/bar/baz/fob"</span>
 <span class=s2>"/foo/bar/baz/fob/42"</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=../operator_slash/ ><code>operator/</code></a> - create <abbr title="JavaScript Object Notation">JSON</abbr> Pointer by appending</li> <li><a href=../push_back/ ><code>push_back</code></a> - append an unescaped token at the end of the pointer</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Pointer support</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 3.6.0.</li> <li>Added in version 3.6.0. Changed type of <code>token</code> to <code>string_t</code> in version 3.11.0.</li> <li>Added in version 3.6.0.</li> </ol> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../operator_slash/ class="md-footer__link md-footer__link--prev" aria-label="Previous: operator/"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> operator/ </div> </div> </a> <a href=../parent_pointer/ class="md-footer__link md-footer__link--next" aria-label="Next: parent_pointer"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> parent_pointer </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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-3Line 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=../operator_slash/ ><code>operator/</code></a> - create <abbr title="JavaScript Object Notation">JSON</abbr> Pointer by appending</li> <li><a href=../push_back/ ><code>push_back</code></a> - append an unescaped token at the end of the pointer</li> <li><a href=../../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - the article on <abbr title="JavaScript Object Notation">JSON</abbr> Pointer support</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ol> <li>Added in version 3.6.0. Appending a <abbr title="JavaScript Object Notation">JSON</abbr> pointer to itself no longer results in undefined behavior in version 3.13.0.</li> <li>Added in version 3.6.0. Changed type of <code>token</code> to <code>string_t</code> in version 3.11.0.</li> <li>Added in version 3.6.0.</li> </ol> <!-- 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 28, 2026 19:23:55 UTC">October 28, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../operator_slash/ class="md-footer__link md-footer__link--prev" aria-label="Previous: operator/"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> operator/ </div> </div> </a> <a href=../parent_pointer/ class="md-footer__link md-footer__link--next" aria-label="Next: parent_pointer"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> parent_pointer </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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 Line truncated
@@ -17,7 +17,7 @@ json_pointer& operator/=(std::size_t array_idx)

 ## Parameters

-`ptr` (in) : JSON pointer to append
+`ptr` (in) : JSON pointer to append; may be the JSON pointer itself (`p /= p`), which then appends a copy of its reference tokens

 `token` (in) : reference token to append

@@ -90,6 +90,6 @@ Output:

 ## Version history

-1. Added in version 3.6.0.
+1. Added in version 3.6.0. Appending a JSON pointer to itself no longer results in undefined behavior in version 3.13.0.
 1. Added in version 3.6.0. Changed type of `token` to `string_t` in version 3.11.0.
 1. Added in version 3.6.0.
@@ -277,6 +277,7 @@ When the macro is not defined, the library will define it to its default value.

 - [:simple-cmake: JSON_Diagnostic_Positions](../../integration/cmake.md#json_diagnostic_positions) - CMake option to control the macro
 - [`JSON_DIAGNOSTICS`](json_diagnostics.md) - macro to control extended diagnostics
+- [`materialize()`](../basic_json_view/materialize.md) - values of a JSON view, with the same positions
 - [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - handling parse errors and locating them in the input

 ## Version history
@@ -165,4 +165,4 @@ Parsed string:
 <span class=p>}</span>
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.302] (/address/housenumber) (bytes 92-95) type must be number, but is string
 </code></pre></div> <div class=codehilite><pre><span></span><code>The output shows the exception with diagnostic path info and start/end positions.
-</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=../../../integration/cmake/#json_diagnostic_positions><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M11.769.066.067 23.206l12.76-10.843zm11.438 23.868L7.471 17.587 0 23.934zm.793-.198L12.298.463l1.719 19.24zM12.893 12.959l-5.025 4.298 5.62 2.248z"/></svg></span> JSON_Diagnostic_Positions</a> - CMake option to control the macro</li> <li><a href=../json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> - macro to control extended diagnostics</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</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.12.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 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../json_delete_deprecated_functions/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON_DELETE_DEPRECATED_FUNCTIONS"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON_DELETE_DEPRECATED_FUNCTIONS </div> </div> </a> <a href=../json_disable_enum_serialization/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON_DISABLE_ENUM_SERIALIZATION"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON_DISABLE_ENUM_SERIALIZATION </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.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=../../../integration/cmake/#json_diagnostic_positions><span class=twemoji><svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M11.769.066.067 23.206l12.76-10.843zm11.438 23.868L7.471 17.587 0 23.934zm.793-.198L12.298.463l1.719 19.24zM12.893 12.959l-5.025 4.298 5.62 2.248z"/></svg></span> JSON_Diagnostic_Positions</a> - CMake option to control the macro</li> <li><a href=../json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> - macro to control extended diagnostics</li> <li><a href=../../basic_json_view/materialize/ ><code>materialize()</code></a> - values of a <abbr title="JavaScript Object Notation">JSON</abbr> view, with the same positions</li> <li><a href=../../../features/parsing/parse_exceptions/ >Parsing and Exceptions</a> - handling parse errors and locating them in the input</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.12.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 28, 2026 19:24:49 UTC">October 28, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../json_delete_deprecated_functions/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON_DELETE_DEPRECATED_FUNCTIONS"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON_DELETE_DEPRECATED_FUNCTIONS </div> </div> </a> <a href=../json_disable_enum_serialization/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON_DISABLE_ENUM_SERIALIZATION"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON_DISABLE_ENUM_SERIALIZATION </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.Line truncated
@@ -256,6 +256,7 @@ The output shows the exception with diagnostic path info and start/end positions

 - [JSON_Diagnostic_Positions](https://json.nlohmann.me/integration/cmake/#json_diagnostic_positions) - CMake option to control the macro
 - [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) - macro to control extended diagnostics
+- [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) - values of a JSON view, with the same positions
 - [Parsing and Exceptions](https://json.nlohmann.me/features/parsing/parse_exceptions/index.md) - handling parse errors and locating them in the input

 ## Version history
@@ -122,8 +122,9 @@ flowchart LR
    - `NaN` and [discarded](../api/basic_json/is_discarded.md) values are not equal to themselves, so the invariant
      cannot hold for them. `diff` emits a `replace` operation for such a value, and a `NaN` in a patch is serialized
      as `#!json null`.
-    - Numbers that compare equal produce no operation even if their types differ: `diff(1, 1.0)`, `diff(1u, 1)`, and
-      `diff(0.0, -0.0)` return `#!json []`, so the patched value keeps the number type of *source*.
+    - Numbers that compare equal produce no operation even if their types differ or if one is zero and the other is
+      negative zero: `diff(1, 1.0)`, `diff(1u, 1)`, and `diff(0.0, -0.0)` return `#!json []`, so the patched value
+      keeps the number type and sign of *source*.
    - A [binary value](binary_values.md) in a patch is serialized as an object
      (`#!json {"bytes":[...],"subtype":null}`), so a patch that was dumped and parsed again no longer holds a binary
      value.
@@ -46,7 +46,7 @@
    S["source"] --&gt;|"diff(source, target)"| P["patch"]
    S --&gt;|"source.patch(patch)"| T["target"]
    P -.-&gt;|"applied to source, yields"| T</code></pre> <p class=nj-caption>How <code>diff</code> and <code>patch</code> relate: <code>diff(source, target)</code> yields a patch, and applying that patch to the source yields the target.</p> <div class="admonition success"> <p class=admonition-title>Invariant</p> <p>For two <abbr title="JavaScript Object Notation">JSON</abbr> values <em>source</em> and <em>target</em>, the following code yields true:</p> <div class=highlight><pre><span></span><code><span class=n>source</span><span class=p>.</span><span class=n>patch</span><span class=p>(</span><span class=n>diff</span><span class=p>(</span><span class=n>source</span><span class=p>,</span><span class=w> </span><span class=n>target</span><span class=p>))</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>target</span><span class=p>;</span>
-</code></pre></div> <p>The equality holds up to <a href=../../api/basic_json/operator_eq/ ><code>operator==</code></a>, with these exceptions:</p> <ul> <li><code>NaN</code> and <a href=../../api/basic_json/is_discarded/ >discarded</a> values are not equal to themselves, so the invariant cannot hold for them. <code>diff</code> emits a <code>replace</code> operation for such a value, and a <code>NaN</code> in a patch is serialized as <code class=highlight><span class=kc>null</span></code>.</li> <li>Numbers that compare equal produce no operation even if their types differ: <code>diff(1, 1.0)</code>, <code>diff(1u, 1)</code>, and <code>diff(0.0, -0.0)</code> return <code class=highlight><span class=p>[]</span></code>, so the patched value keeps the number type of <em>source</em>.</li> <li>A <a href=../binary_values/ >binary value</a> in a patch is serialized as an object (<code class=highlight><span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=err>...</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=kc>null</span><span class=p>}</span></code>), so a patch that was dumped and parsed again no longer holds a binary value.</li> </ul> </div> <details class=example> <summary>Example: create a <abbr title="JavaScript Object Notation">JSON</abbr> Patch from the difference of two values</summary> <p>The following code shows how a <abbr title="JavaScript Object Notation">JSON</abbr> patch is created as a diff for two <abbr title="JavaScript Object Notation">JSON</abbr> values.</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>The equality holds up to <a href=../../api/basic_json/operator_eq/ ><code>operator==</code></a>, with these exceptions:</p> <ul> <li><code>NaN</code> and <a href=../../api/basic_json/is_discarded/ >discarded</a> values are not equal to themselves, so the invariant cannot hold for them. <code>diff</code> emits a <code>replace</code> operation for such a value, and a <code>NaN</code> in a patch is serialized as <code class=highlight><span class=kc>null</span></code>.</li> <li>Numbers that compare equal produce no operation even if their types differ or if one is zero and the other is negative zero: <code>diff(1, 1.0)</code>, <code>diff(1u, 1)</code>, and <code>diff(0.0, -0.0)</code> return <code class=highlight><span class=p>[]</span></code>, so the patched value keeps the number type and sign of <em>source</em>.</li> <li>A <a href=../binary_values/ >binary value</a> in a patch is serialized as an object (<code class=highlight><span class=p>{</span><span class=nt>"bytes"</span><span class=p>:[</span><span class=err>...</span><span class=p>],</span><span class=nt>"subtype"</span><span class=p>:</span><span class=kc>null</span><span class=p>}</span></code>), so a patch that was dumped and parsed again no longer holds a binary value.</li> </ul> </div> <details class=example> <summary>Example: create a <abbr title="JavaScript Object Notation">JSON</abbr> Patch from the difference of two values</summary> <p>The following code shows how a <abbr title="JavaScript Object Notation">JSON</abbr> patch is created as a diff for two <abbr title="JavaScript Object Notation">JSON</abbr> values.</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;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>

@@ -108,4 +108,4 @@
 <span class=w>        </span><span class=s2>"world"</span>
 <span class=w>    </span><span class=p>]</span>
 <span class=p>}</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - the addressing scheme used for patch paths</li> <li><a href=../merge_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</a> - a simpler, less expressive alternative patch format</li> <li><a href=../../api/basic_json/patch/ ><code>patch</code></a> - apply a <abbr title="JavaScript Object Notation">JSON</abbr> Patch, returning the result as a copy</li> <li><a href=../../api/basic_json/patch_inplace/ ><code>patch_inplace</code></a> - apply a <abbr title="JavaScript Object Notation">JSON</abbr> Patch without copying</li> <li><a href=../../api/basic_json/diff/ ><code>diff</code></a> - compute a <abbr title="JavaScript Object Notation">JSON</abbr> Patch from two values</li> <li><a href=../../api/json_pointer/ ><code>json_pointer</code></a> - type to represent <abbr title="JavaScript Object Notation">JSON</abbr> Pointers</li> <li><a href=../../api/basic_json/merge_diff/ ><code>merge_diff</code></a> - compute a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch from two values</li> <li><a href=../modifying_values/ >Modifying values</a> - simple in-place 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 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../merge_patch/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON Merge Patch"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON Merge Patch </div> </div> </a> <a href=../json_pointer/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON Pointer"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON Pointer </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.3Line 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=../json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> - the addressing scheme used for patch paths</li> <li><a href=../merge_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch</a> - a simpler, less expressive alternative patch format</li> <li><a href=../../api/basic_json/patch/ ><code>patch</code></a> - apply a <abbr title="JavaScript Object Notation">JSON</abbr> Patch, returning the result as a copy</li> <li><a href=../../api/basic_json/patch_inplace/ ><code>patch_inplace</code></a> - apply a <abbr title="JavaScript Object Notation">JSON</abbr> Patch without copying</li> <li><a href=../../api/basic_json/diff/ ><code>diff</code></a> - compute a <abbr title="JavaScript Object Notation">JSON</abbr> Patch from two values</li> <li><a href=../../api/json_pointer/ ><code>json_pointer</code></a> - type to represent <abbr title="JavaScript Object Notation">JSON</abbr> Pointers</li> <li><a href=../../api/basic_json/merge_diff/ ><code>merge_diff</code></a> - compute a <abbr title="JavaScript Object Notation">JSON</abbr> Merge Patch from two values</li> <li><a href=../modifying_values/ >Modifying values</a> - simple in-place 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 27, 2026 16:16:08 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../merge_patch/ class="md-footer__link md-footer__link--prev" aria-label="Previous: JSON Merge Patch"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> JSON Merge Patch </div> </div> </a> <a href=../json_pointer/ class="md-footer__link md-footer__link--next" aria-label="Next: JSON Pointer"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> JSON Pointer </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &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.3Line truncated
@@ -105,7 +105,7 @@ source.patch(diff(source, target)) == target;
 The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), with these exceptions:

 - `NaN` and [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values are not equal to themselves, so the invariant cannot hold for them. `diff` emits a `replace` operation for such a value, and a `NaN` in a patch is serialized as `null`.
- Numbers that compare equal produce no operation even if their types differ: `diff(1, 1.0)`, `diff(1u, 1)`, and `diff(0.0, -0.0)` return `[]`, so the patched value keeps the number type of *source*.
+- Numbers that compare equal produce no operation even if their types differ or if one is zero and the other is negative zero: `diff(1, 1.0)`, `diff(1u, 1)`, and `diff(0.0, -0.0)` return `[]`, so the patched value keeps the number type and sign of *source*.
 - A [binary value](https://json.nlohmann.me/features/binary_values/index.md) in a patch is serialized as an object (`{"bytes":[...],"subtype":null}`), so a patch that was dumped and parsed again no longer holds a binary value.

 Example: create a JSON Patch from the difference of two values
@@ -447,10 +447,12 @@ document: `#!cpp auto v = json_document::parse(text).root();` does not compile.
  end must still fit.
 - **A stream is always read to its end.** There is no partial/streaming read of an `#!cpp std::istream`: the stream
  is read to its end into a buffer the document owns, and parsing starts after that.
- **No source positions on `materialize()`.** Even with
+- **Fewer source positions after edits.** With
  [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md) enabled,
-  [`materialize()`](../api/basic_json_view/materialize.md) does not set them. The index has the start offset of every
-  value, but not the end of arrays, objects, and escaped strings, which the positions also need.
+  [`materialize()`](../api/basic_json_view/materialize.md) sets the same positions as `#!cpp basic_json::parse()`.
+  In an [editable document](../api/json_editable_document.md), a value written by an edit has none, and neither has
+  an array or object whose elements changed or whose last element has none; a `basic_json` value keeps its positions
+  when it is changed. See [`materialize()`](../api/basic_json_view/materialize.md#notes).
 - **Objects iterate in document order.** [`begin()`](../api/basic_json_view/begin.md)/
  [`end()`](../api/basic_json_view/end.md) and [`items()`](../api/basic_json_view/items.md) visit an object's
  members in the order they appear in the source text. `basic_json`'s default `object_t` is a `std::map`, which
@@ -53,7 +53,7 @@
 <span class=kc>true</span>
 <span class=kc>true</span>
 <span class=kc>true</span>
-</code></pre></div> </details> <h2 id=what-is-the-same-as-parse>What is the same as <code>parse()</code><a class=headerlink href=#what-is-the-same-as-parse title="Permanent link">&para;</a></h2> <ul> <li><strong>Accept/reject.</strong> <a href=../../api/basic_json_document/accept/ ><code>accept()</code></a> and <a href=../../api/basic_json_document/parse/ ><code>parse()</code></a> accept and reject exactly the same inputs as <a href=../../api/basic_json/accept/ ><code>basic_json::accept()</code></a>/<a href=../../api/basic_json/parse/ ><code>basic_json::parse()</code></a>, with the same <code>ignore_comments</code> and <code>ignore_trailing_commas</code> options.</li> <li><strong>Errors.</strong> A failing parse throws the same exception — the same id, message, and position — because on failure the library's own parser is run on the same bytes to produce the diagnostic. Valid input never pays for this, and the replay builds no values: it costs about a lexing pass up to the error. <code class=highlight><span class=n>allow_exceptions</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>false</span></code> skips the replay and gives a <a href=../../api/basic_json_document/is_discarded/ >discarded</a> document instead of throwing, just as it gives a discarded value for <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code>.</li> <li><strong>Number classification.</strong> An integer literal that does not fit into the 64-bit integer type becomes a floating-point value, exactly as it does for <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code>.</li> <li><strong>Macros.</strong> <a href=../../api/macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> and <a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a>/<a href=../../api/macros/json_throw_user/ ><code>JSON_THROW_USER</code></a> behave the same way they do for <code>&lt;nlohmann/json.hpp&gt;</code>. These are the macros that change what the parser accepts or how it reports errors. The others either do not apply (<a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> needs parent pointers in <code>basic_json</code> values) or only affect the values <code>materialize()</code> produces, through <code>BasicJsonType</code>.</li> </ul> <h2 id=what-is-different>What is different<a class=headerlink href=#what-is-different title="Permanent link">&para;</a></h2> <ul> <li><strong>Only 64-bit integers.</strong> <code>basic_json_document&lt;BasicJsonType&gt;</code> requires <code>BasicJsonType::number_integer_t</code> and <code>number_unsigned_t</code> to both be 64 bits wide; this is a compile-time <code class=highlight><span class=k>static_assert</span></code>.</li> <li><strong>A 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> input limit.</strong> An input of 4294967280 bytes (4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes) or more throws <a href=../../home/exceptions/#jsonexceptionout_of_range416><code>out_of_range.416</code></a>, a limit <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code> does not have. It keeps an index entry at 16 bytes: offsets and counts are 32 bits wide. The limit is 16 bytes below 2^32, because the parser reads in 16-byte steps, and a position one step past the end must still fit.</li> <li><strong>A stream is always read to its end.</strong> There is no partial/streaming read of an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>: the stream is read to its end into a buffer the document owns, and parsing starts after that.</li> <li><strong>No source positions on <code>materialize()</code>.</strong> Even with <a href=../../api/macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> enabled, <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a> does not set them. The index has the start offset of every value, but not the end of arrays, objects, and escaped strings, which the positions also need.</li> <li><strong>Objects iterate in document order.</strong> <a href=../../api/basic_json_view/begin/ ><code>begin()</code></a>/ <a href=../../api/basic_json_view/end/ ><code>end()</code></a> and <a href=../../api/basic_json_view/items/ ><code>items()</code></a> visit an object's members in the order they appear in the source text. <code>basic_json</code>'s default <code>object_t</code> is a <code>std::map</code>, which sorts by key, so iterating a <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a>d value can print members in a different order than iterating the view they came from.</li> <li><strong>Chained access is safe.</strong> <a href=../../api/basic_json_view/operLine truncated
+</code></pre></div> </details> <h2 id=what-is-the-same-as-parse>What is the same as <code>parse()</code><a class=headerlink href=#what-is-the-same-as-parse title="Permanent link">&para;</a></h2> <ul> <li><strong>Accept/reject.</strong> <a href=../../api/basic_json_document/accept/ ><code>accept()</code></a> and <a href=../../api/basic_json_document/parse/ ><code>parse()</code></a> accept and reject exactly the same inputs as <a href=../../api/basic_json/accept/ ><code>basic_json::accept()</code></a>/<a href=../../api/basic_json/parse/ ><code>basic_json::parse()</code></a>, with the same <code>ignore_comments</code> and <code>ignore_trailing_commas</code> options.</li> <li><strong>Errors.</strong> A failing parse throws the same exception — the same id, message, and position — because on failure the library's own parser is run on the same bytes to produce the diagnostic. Valid input never pays for this, and the replay builds no values: it costs about a lexing pass up to the error. <code class=highlight><span class=n>allow_exceptions</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=nb>false</span></code> skips the replay and gives a <a href=../../api/basic_json_document/is_discarded/ >discarded</a> document instead of throwing, just as it gives a discarded value for <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code>.</li> <li><strong>Number classification.</strong> An integer literal that does not fit into the 64-bit integer type becomes a floating-point value, exactly as it does for <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code>.</li> <li><strong>Macros.</strong> <a href=../../api/macros/json_strict_nul_handling/ ><code>JSON_STRICT_NUL_HANDLING</code></a> and <a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a>/<a href=../../api/macros/json_throw_user/ ><code>JSON_THROW_USER</code></a> behave the same way they do for <code>&lt;nlohmann/json.hpp&gt;</code>. These are the macros that change what the parser accepts or how it reports errors. The others either do not apply (<a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> needs parent pointers in <code>basic_json</code> values) or only affect the values <code>materialize()</code> produces, through <code>BasicJsonType</code>.</li> </ul> <h2 id=what-is-different>What is different<a class=headerlink href=#what-is-different title="Permanent link">&para;</a></h2> <ul> <li><strong>Only 64-bit integers.</strong> <code>basic_json_document&lt;BasicJsonType&gt;</code> requires <code>BasicJsonType::number_integer_t</code> and <code>number_unsigned_t</code> to both be 64 bits wide; this is a compile-time <code class=highlight><span class=k>static_assert</span></code>.</li> <li><strong>A 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> input limit.</strong> An input of 4294967280 bytes (4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes) or more throws <a href=../../home/exceptions/#jsonexceptionout_of_range416><code>out_of_range.416</code></a>, a limit <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code> does not have. It keeps an index entry at 16 bytes: offsets and counts are 32 bits wide. The limit is 16 bytes below 2^32, because the parser reads in 16-byte steps, and a position one step past the end must still fit.</li> <li><strong>A stream is always read to its end.</strong> There is no partial/streaming read of an <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>istream</span></code>: the stream is read to its end into a buffer the document owns, and parsing starts after that.</li> <li><strong>Fewer source positions after edits.</strong> With <a href=../../api/macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a> enabled, <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a> sets the same positions as <code class=highlight><span class=n>basic_json</span><span class=o>::</span><span class=n>parse</span><span class=p>()</span></code>. In an <a href=../../api/json_editable_document/ >editable document</a>, a value written by an edit has none, and neither has an array or object whose elements changed or whose last element has none; a <code>basic_json</code> value keeps its positions when it is changed. See <a href=../../api/basic_json_view/materialize/#notes><code>materialize()</code></a>.</li> <li><strong>Objects iterate in document order.</strong> <a href=../../api/basic_json_view/begin/ ><code>begin()</code></a>/ <a href=../../api/basic_json_view/end/ ><code>end()</code></a> and <a href=../../api/basic_json_view/items/ ><code>items()</code></a> visit an object's members in the order they appear in the source text. <code>basic_json</code>'sLine truncated
 <span class=n>json_view</span><span class=w> </span><span class=n>last</span><span class=p>;</span>
 <span class=k>for</span><span class=w> </span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=k>auto</span><span class=w> </span><span class=n>item</span><span class=w> </span><span class=o>:</span><span class=w> </span><span class=n>view</span><span class=p>.</span><span class=n>items</span><span class=p>())</span>
 <span class=p>{</span>
@@ -161,4 +161,4 @@
 </code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=mi>316</span>
 <span class=kc>true</span>
 <span class=kc>true</span>
-</code></pre></div> </details> <div class="admonition warning"> <p class=admonition-title>Experimental</p> <p>The image format is versioned but not yet stable, and may change in an incompatible way before it is declared stable. It is little-endian only (on big-endian targets, <code>save()</code> and <code>load()</code> do not exist), and tied to the library build that wrote it — use it to cache a document or to hand one to another process running the <em>same</em> build, not as a long-term storage format; keep the original <abbr title="JavaScript Object Notation">JSON</abbr> text if a saved document needs to be readable by a future library version.</p> </div> <p>The idea of a document you can read without parsing comes from zero-copy formats such as <a href="https://github.com/google/flatbuffers">FlatBuffers</a> and <a href="https://github.com/yandex/yaff">YaFF</a>; the check <a href=../../api/basic_json_document/load/ ><code>load()</code></a> runs follows the idea of FlatBuffers' Verifier. No code is taken from either.</p> <h2 id=choosing-between-json-ordered_json-the-sax-interface-and-json_view>Choosing between <code>json</code>, <code>ordered_json</code>, the <abbr title="Simple API for XML">SAX</abbr> interface, and <code>json_view</code><a class=headerlink href=#choosing-between-json-ordered_json-the-sax-interface-and-json_view title="Permanent link">&para;</a></h2> <table> <thead> <tr> <th></th> <th><a href=../../api/json/ ><code>json</code></a> / <a href=../../api/ordered_json/ ><code>ordered_json</code></a></th> <th><a href=../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a></th> <th><a href=../../api/json_document/ ><code>json_document</code></a> / <a href=../../api/json_view/ ><code>json_view</code></a></th> <th><a href=../../api/json_editable_document/ ><code>json_editable_document</code></a> / <a href=../../api/json_editable_view/ ><code>json_editable_view</code></a></th> </tr> </thead> <tbody> <tr> <td><strong>Ownership</strong></td> <td>owns every value</td> <td>owns nothing; you decide what to keep, in your handler</td> <td>borrows or owns the <em>text</em>; the index is always owned by the document</td> <td>same as <code>json_document</code>; edits go to storage the document owns</td> </tr> <tr> <td><strong>Mutability</strong></td> <td>freely mutable</td> <td>not applicable (a one-shot event stream)</td> <td>read-only</td> <td><a href=../../api/basic_json_document/set/ ><code>set</code></a>/<a href=../../api/basic_json_document/push_back/ ><code>push_back</code></a>/<a href=../../api/basic_json_document/insert/ ><code>insert</code></a>/<a href=../../api/basic_json_document/erase/ ><code>erase</code></a> edit in place; the source text is never rewritten</td> </tr> <tr> <td><strong>What you get</strong></td> <td>a full tree you can read, write, and keep as long as you like</td> <td>a sequence of callbacks; whatever your handler builds from them</td> <td>a flat index plus, on demand, <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a>d <code>json</code>/<code>ordered_json</code> values for the parts you actually use</td> <td>the same, plus <a href=../../api/basic_json_view/dump/ ><code>dump()</code></a> of an edited document that keeps the member order and, with <a href=../../api/basic_json_view/number_format/ ><code>number_format::source</code></a>, the spelling of every untouched number</td> </tr> <tr> <td><strong>Typical use</strong></td> <td>general-purpose <abbr title="JavaScript Object Notation">JSON</abbr> handling: config, request/response bodies you build or modify, anything you hold onto</td> <td>validating or projecting a text into your own data structure without ever holding the whole thing as <abbr title="JavaScript Object Notation">JSON</abbr></td> <td>large or high-volume input where you only need part of it, or need it repeatedly, and can keep the source text (or a copy) alive for as long as the document lives</td> <td>a document you read, patch a few fields of, and write back — a configuration file, for instance — where the rest of it should come back exactly as it was</td> </tr> <tr> <td><strong>Caching/reload</strong></td> <td>not applicable — re-parse, or roll your own serialization</td> <td>not applicable</td> <td><a href=../../api/basic_json_document/save/ ><code>save()</code></a>/<a href=../../api/basic_json_document/load/ ><code>load()</code></a>: cache the parsed index as an image and reload it without parsing</td> <td>same, saving the document's current — possibly edited — state</td> </tr> </tbody> </table> <p class=nj-table-caption>Each column is one way to work with <abbr title="JavaScript Object Notation">JSON</abbr> in this library, and each row compares one property of them.</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_document/ ><code>basic_json_document</code></a> - the document that owns the parsLine truncated
+</code></pre></div> </details> <div class="admonition warning"> <p class=admonition-title>Experimental</p> <p>The image format is versioned but not yet stable, and may change in an incompatible way before it is declared stable. It is little-endian only (on big-endian targets, <code>save()</code> and <code>load()</code> do not exist), and tied to the library build that wrote it — use it to cache a document or to hand one to another process running the <em>same</em> build, not as a long-term storage format; keep the original <abbr title="JavaScript Object Notation">JSON</abbr> text if a saved document needs to be readable by a future library version.</p> </div> <p>The idea of a document you can read without parsing comes from zero-copy formats such as <a href="https://github.com/google/flatbuffers">FlatBuffers</a> and <a href="https://github.com/yandex/yaff">YaFF</a>; the check <a href=../../api/basic_json_document/load/ ><code>load()</code></a> runs follows the idea of FlatBuffers' Verifier. No code is taken from either.</p> <h2 id=choosing-between-json-ordered_json-the-sax-interface-and-json_view>Choosing between <code>json</code>, <code>ordered_json</code>, the <abbr title="Simple API for XML">SAX</abbr> interface, and <code>json_view</code><a class=headerlink href=#choosing-between-json-ordered_json-the-sax-interface-and-json_view title="Permanent link">&para;</a></h2> <table> <thead> <tr> <th></th> <th><a href=../../api/json/ ><code>json</code></a> / <a href=../../api/ordered_json/ ><code>ordered_json</code></a></th> <th><a href=../parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a></th> <th><a href=../../api/json_document/ ><code>json_document</code></a> / <a href=../../api/json_view/ ><code>json_view</code></a></th> <th><a href=../../api/json_editable_document/ ><code>json_editable_document</code></a> / <a href=../../api/json_editable_view/ ><code>json_editable_view</code></a></th> </tr> </thead> <tbody> <tr> <td><strong>Ownership</strong></td> <td>owns every value</td> <td>owns nothing; you decide what to keep, in your handler</td> <td>borrows or owns the <em>text</em>; the index is always owned by the document</td> <td>same as <code>json_document</code>; edits go to storage the document owns</td> </tr> <tr> <td><strong>Mutability</strong></td> <td>freely mutable</td> <td>not applicable (a one-shot event stream)</td> <td>read-only</td> <td><a href=../../api/basic_json_document/set/ ><code>set</code></a>/<a href=../../api/basic_json_document/push_back/ ><code>push_back</code></a>/<a href=../../api/basic_json_document/insert/ ><code>insert</code></a>/<a href=../../api/basic_json_document/erase/ ><code>erase</code></a> edit in place; the source text is never rewritten</td> </tr> <tr> <td><strong>What you get</strong></td> <td>a full tree you can read, write, and keep as long as you like</td> <td>a sequence of callbacks; whatever your handler builds from them</td> <td>a flat index plus, on demand, <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a>d <code>json</code>/<code>ordered_json</code> values for the parts you actually use</td> <td>the same, plus <a href=../../api/basic_json_view/dump/ ><code>dump()</code></a> of an edited document that keeps the member order and, with <a href=../../api/basic_json_view/number_format/ ><code>number_format::source</code></a>, the spelling of every untouched number</td> </tr> <tr> <td><strong>Typical use</strong></td> <td>general-purpose <abbr title="JavaScript Object Notation">JSON</abbr> handling: config, request/response bodies you build or modify, anything you hold onto</td> <td>validating or projecting a text into your own data structure without ever holding the whole thing as <abbr title="JavaScript Object Notation">JSON</abbr></td> <td>large or high-volume input where you only need part of it, or need it repeatedly, and can keep the source text (or a copy) alive for as long as the document lives</td> <td>a document you read, patch a few fields of, and write back — a configuration file, for instance — where the rest of it should come back exactly as it was</td> </tr> <tr> <td><strong>Caching/reload</strong></td> <td>not applicable — re-parse, or roll your own serialization</td> <td>not applicable</td> <td><a href=../../api/basic_json_document/save/ ><code>save()</code></a>/<a href=../../api/basic_json_document/load/ ><code>load()</code></a>: cache the parsed index as an image and reload it without parsing</td> <td>same, saving the document's current — possibly edited — state</td> </tr> </tbody> </table> <p class=nj-table-caption>Each column is one way to work with <abbr title="JavaScript Object Notation">JSON</abbr> in this library, and each row compares one property of them.</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_document/ ><code>basic_json_document</code></a> - the document that owns the parsLine truncated
@@ -130,7 +130,7 @@ true
 - **Only 64-bit integers.** `basic_json_document<BasicJsonType>` requires `BasicJsonType::number_integer_t` and `number_unsigned_t` to both be 64 bits wide; this is a compile-time `static_assert`.
 - **A 4 GiB input limit.** An input of 4294967280 bytes (4 GiB minus 16 bytes) or more throws [`out_of_range.416`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range416), a limit `basic_json::parse()` does not have. It keeps an index entry at 16 bytes: offsets and counts are 32 bits wide. The limit is 16 bytes below 2^32, because the parser reads in 16-byte steps, and a position one step past the end must still fit.
 - **A stream is always read to its end.** There is no partial/streaming read of an `std::istream`: the stream is read to its end into a buffer the document owns, and parsing starts after that.
- **No source positions on `materialize()`.** Even with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) enabled, [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) does not set them. The index has the start offset of every value, but not the end of arrays, objects, and escaped strings, which the positions also need.
+- **Fewer source positions after edits.** With [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) enabled, [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets the same positions as `basic_json::parse()`. In an [editable document](https://json.nlohmann.me/api/json_editable_document/index.md), a value written by an edit has none, and neither has an array or object whose elements changed or whose last element has none; a `basic_json` value keeps its positions when it is changed. See [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/#notes).
 - **Objects iterate in document order.** [`begin()`](https://json.nlohmann.me/api/basic_json_view/begin/index.md)/ [`end()`](https://json.nlohmann.me/api/basic_json_view/end/index.md) and [`items()`](https://json.nlohmann.me/api/basic_json_view/items/index.md) visit an object's members in the order they appear in the source text. `basic_json`'s default `object_t` is a `std::map`, which sorts by key, so iterating a [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md)d value can print members in a different order than iterating the view they came from.
 - **Chained access is safe.** [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) with a missing key, an index out of range, or an unresolvable JSON pointer returns a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view, and `operator[]` on a discarded view returns a discarded view without throwing: `v["a"]["b"][0]` can be tested once at the end. Type errors on values that exist (a key on an array, an index on an object) still throw, and [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md) throws for every missing value.
 - **Duplicate keys: lookups find the first member, `parse()` keeps the last.** See [Duplicate keys](#duplicate-keys) below.
@@ -130,6 +130,17 @@ parameters of [`parse()`](../../api/basic_json/parse.md) or [`accept()`](../../a
 enable either for input whose conformance you cannot otherwise control, since interoperability with strictly
 conforming JSON consumers is exactly what the default rejects.

+## JSON Pointers and flattened keys
+
+A [JSON Pointer](../json_pointer.md) can come from untrusted input as well, for instance as a path in a request or as a
+key of a flattened object. The non-const [`operator[]`](../../api/basic_json/operator%5B%5D.md) with a JSON Pointer and
+[`unflatten`](../../api/basic_json/unflatten.md) create missing values, and when an array index lies beyond the end of
+an array, they fill the array with `#!json null` values up to that index. The memory used therefore grows with the
+index, not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB, the index
+`100000000` about 1.6 GB. The library does not limit the index. For pointers from untrusted input, check the array
+indices (or the pointer as a whole) before using them, or use [`at`](../../api/basic_json/at.md) or
+[`contains`](../../api/basic_json/contains.md), which never add values.
+
 ## Checklist

 - Wrap parsing in a `#!cpp try`/`#!cpp catch` block, or use `allow_exceptions=false`/`accept()` if your environment
@@ -145,6 +156,8 @@ conforming JSON consumers is exactly what the default rejects.
  `JSON_STRICT_NUL_HANDLING`.
 - Decide whether duplicate object keys should be an error for your application, and add a callback if so.
 - Do not enable `ignore_comments` or `ignore_trailing_commas` for input that must be strictly conforming JSON.
+- Check the array indices of untrusted JSON Pointers and flattened keys before passing them to the non-const
+  `operator[]` or `unflatten()`, which fill arrays with `#!json null` values up to the index.

 For the broader design rationale and how it is tested (fuzzing, sanitizers, static analysis), see the
 [assurance case](../../community/assurance_case.md) and [quality assurance](../../community/quality_assurance.md). To
@@ -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=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#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> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> 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=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svgLine truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#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> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> 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=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svgLine truncated
@@ -58,6 +58,10 @@ A number whose value cannot be represented — for instance `1E1000`, which over

 Both [comments](https://json.nlohmann.me/features/comments/index.md) and [trailing commas](https://json.nlohmann.me/features/trailing_commas/index.md) are rejected by default, matching the JSON specification; they must be explicitly enabled per call with the `ignore_comments` and `ignore_trailing_commas` parameters of [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) or [`accept()`](https://json.nlohmann.me/api/basic_json/accept/index.md). Do not enable either for input whose conformance you cannot otherwise control, since interoperability with strictly conforming JSON consumers is exactly what the default rejects.

+## JSON Pointers and flattened keys
+
+A [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md) can come from untrusted input as well, for instance as a path in a request or as a key of a flattened object. The non-const [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) with a JSON Pointer and [`unflatten`](https://json.nlohmann.me/api/basic_json/unflatten/index.md) create missing values, and when an array index lies beyond the end of an array, they fill the array with `null` values up to that index. The memory used therefore grows with the index, not with the size of the pointer: on a 64-bit platform, the index `10000000` allocates about 160 MB, the index `100000000` about 1.6 GB. The library does not limit the index. For pointers from untrusted input, check the array indices (or the pointer as a whole) before using them, or use [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) or [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md), which never add values.
+
 ## Checklist

 - Wrap parsing in a `try`/`catch` block, or use `allow_exceptions=false`/`accept()` if your environment cannot use exceptions; never let `JSON_NOEXCEPTION`'s `abort()` be the first time you think about error handling.
@@ -67,6 +71,7 @@ Both [comments](https://json.nlohmann.me/features/comments/index.md) and [traili
 - If a stray NUL byte silently truncating trailing input is a problem for your input format, define `JSON_STRICT_NUL_HANDLING`.
 - Decide whether duplicate object keys should be an error for your application, and add a callback if so.
 - Do not enable `ignore_comments` or `ignore_trailing_commas` for input that must be strictly conforming JSON.
+- Check the array indices of untrusted JSON Pointers and flattened keys before passing them to the non-const `operator[]` or `unflatten()`, which fill arrays with `null` values up to the index.

 For the broader design rationale and how it is tested (fuzzing, sanitizers, static analysis), see the [assurance case](https://json.nlohmann.me/community/assurance_case/index.md) and [quality assurance](https://json.nlohmann.me/community/quality_assurance/index.md). To report a security issue in the library itself, follow the [security policy](https://json.nlohmann.me/community/security_policy/index.md).

@@ -203,7 +203,7 @@ packet-beta
 | 2-3   | `extra` | `uint16_t` | numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0 |
 | 4-7   | `off`   | `uint32_t` | where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object |
 | 8-11  | `len`   | `uint32_t` | strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements |
-| 12-15 | `next`  | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself                                              |
+| 12-15 | `next`  | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself; strings with escapes: the position of the opening quote in the source plus one if the document was parsed with [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md), or 0 if it was not; all other values: 0 |

 <p class="nj-table-caption" markdown>Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.</p>

@@ -218,6 +218,12 @@ packet-beta
  step from element to element this way and skip whole subtrees in constant time.
 - **Offsets** are 32 bits wide, so a document is limited to 4294967279 bytes, 4 GiB minus 16 bytes (a margin below
  2^32 for positions one scanner step past the end of the text; `out_of_range.416`).
+- **Source positions** ([`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md)) are derived by
+  [`materialize()`](../api/basic_json_view/materialize.md) and cost almost nothing while parsing: the only work is
+  storing the offset of the opening quote of a string with escapes in its `next`, which is otherwise unused. A
+  scalar's range follows from `off` and its length, a string with escapes is scanned from its opening quote (`next`) to the closing one,
+  and the end of an array or object is found by scanning from the end of its last element over whitespace, comments,
+  and a trailing comma. `materialize()` hands these positions to the SAX builder of `parse()` in place of its lexer.
 - **Large objects** (128 members or more) get a hash index for their keys after parsing
  ([`detail/view/object_index.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp)):
  an open-addressing table whose slots hold the distance from the object's node to a key's node, so that a lookup does
@@ -277,7 +283,7 @@ Images ([`save`](../api/basic_json_document/save.md) and [`load`](../api/basic_j
 the nodes as they are: a 64-byte header (the magic bytes `NJVI`, a format version, the sizes, and reserved bytes that
 must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as
 the parser would have written it (without links), and the numbers of the hash indexes are cleared, since `load`
-rebuilds the indexes. So a change of the node layout is a change of the image format: it must raise `image_version`,
+rebuilds the indexes. The flag *new* is kept, as these values have no position in the text. So a change of the node layout is a change of the image format: it must raise `image_version`,
 and `load` then rejects images of other versions (`parse_error.116`) instead of misreading them.

 ## Input adapters
@@ -65,7 +65,7 @@
  16-31: "extra"
  32-63: "off"
  64-95: "len"
-  96-127: "next"</code></pre> <p class=nj-caption>Layout of one 16-byte node of a <abbr title="JavaScript Object Notation">JSON</abbr> view index. Each row is 32 bits wide, and the numbers are the bit offsets of the fields <code>kind</code>, <code>flags</code>, <code>extra</code>, <code>off</code>, <code>len</code>, and <code>next</code>.</p> <table> <thead> <tr> <th>Bytes</th> <th>Field</th> <th>Type</th> <th>Contents</th> </tr> </thead> <tbody> <tr> <td>0</td> <td><code>kind</code></td> <td><code>uint8_t</code></td> <td>the type, numbered as <a href=../../api/basic_json/value_t/ ><code>value_t</code></a>: 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a <a href=../../api/basic_json_view/is_discarded/ >discarded</a> view has none</td> </tr> <tr> <td>1</td> <td><code>flags</code></td> <td><code>uint8_t</code></td> <td>bits 0-1: where a string's bytes (or a number's token) are (0: the source text, 1: the buffer of decoded strings, for strings with escapes, 2: the edit buffer); bit 2: the value of a boolean; bit 3: moved, bit 4: new, bit 5: linked (see below)</td> </tr> <tr> <td>2-3</td> <td><code>extra</code></td> <td><code>uint16_t</code></td> <td>numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0</td> </tr> <tr> <td>4-7</td> <td><code>off</code></td> <td><code>uint32_t</code></td> <td>where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object</td> </tr> <tr> <td>8-11</td> <td><code>len</code></td> <td><code>uint32_t</code></td> <td>strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements</td> </tr> <tr> <td>12-15</td> <td><code>next</code></td> <td><code>uint32_t</code></td> <td>arrays and objects: the number of nodes of the subtree, including the node itself</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.</p> <ul> <li><strong>Integers</strong> keep their converted value in bytes 8-15 instead of <code>len</code> and <code>next</code>; the length of their token follows from the number of digits in <code>extra</code> (and the sign). Non-negative integers are unsigned integers, as with <a href=../../api/basic_json/parse/ ><code>parse</code></a>.</li> <li><strong>Floats</strong> keep only their token. The digit layout in <code>extra</code> lets the conversion read the digits without scanning the token again, and only when the value is read.</li> <li><strong>Object members</strong> are the node of the key (a string) followed by the nodes of the value.</li> <li><strong>Navigation</strong> needs no pointers: the elements of an array or object follow its node, and the node after a value's subtree is <code>next</code> nodes further for an array or object, and the next node otherwise (<code>document_data::after</code>). Views step from element to element this way and skip whole subtrees in constant time.</li> <li><strong>Offsets</strong> are 32 bits wide, so a document is limited to 4294967279 bytes, 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes (a margin below 2^32 for positions one scanner step past the end of the text; <code>out_of_range.416</code>).</li> <li><strong>Large objects</strong> (128 members or more) get a hash index for their keys after parsing (<a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp"><code>detail/view/object_index.hpp</code></a>): an open-addressing table whose slots hold the distance from the object's node to a key's node, so that a lookup does not compare every key. Of duplicate keys the table leads to the first, as a linear search does. The object's <code>extra</code> holds the number of its table. Only 65,535 tables fit into <code>extra</code>; objects beyond them are searched linearly.</li> </ul> <p>For example, <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> becomes five nodes. Each node's elements follow it, and <code>next</code> leads from an array or object past its subtree:</p> <pre class=mermaid><code>flowchart LR
+  96-127: "next"</code></pre> <p class=nj-caption>Layout of one 16-byte node of a <abbr title="JavaScript Object Notation">JSON</abbr> view index. Each row is 32 bits wide, and the numbers are the bit offsets of the fields <code>kind</code>, <code>flags</code>, <code>extra</code>, <code>off</code>, <code>len</code>, and <code>next</code>.</p> <table> <thead> <tr> <th>Bytes</th> <th>Field</th> <th>Type</th> <th>Contents</th> </tr> </thead> <tbody> <tr> <td>0</td> <td><code>kind</code></td> <td><code>uint8_t</code></td> <td>the type, numbered as <a href=../../api/basic_json/value_t/ ><code>value_t</code></a>: 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a <a href=../../api/basic_json_view/is_discarded/ >discarded</a> view has none</td> </tr> <tr> <td>1</td> <td><code>flags</code></td> <td><code>uint8_t</code></td> <td>bits 0-1: where a string's bytes (or a number's token) are (0: the source text, 1: the buffer of decoded strings, for strings with escapes, 2: the edit buffer); bit 2: the value of a boolean; bit 3: moved, bit 4: new, bit 5: linked (see below)</td> </tr> <tr> <td>2-3</td> <td><code>extra</code></td> <td><code>uint16_t</code></td> <td>numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0</td> </tr> <tr> <td>4-7</td> <td><code>off</code></td> <td><code>uint32_t</code></td> <td>where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object</td> </tr> <tr> <td>8-11</td> <td><code>len</code></td> <td><code>uint32_t</code></td> <td>strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements</td> </tr> <tr> <td>12-15</td> <td><code>next</code></td> <td><code>uint32_t</code></td> <td>arrays and objects: the number of nodes of the subtree, including the node itself; strings with escapes: the position of the opening quote in the source plus one if the document was parsed with <a href=../../api/macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a>, or 0 if it was not; all other values: 0</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.</p> <ul> <li><strong>Integers</strong> keep their converted value in bytes 8-15 instead of <code>len</code> and <code>next</code>; the length of their token follows from the number of digits in <code>extra</code> (and the sign). Non-negative integers are unsigned integers, as with <a href=../../api/basic_json/parse/ ><code>parse</code></a>.</li> <li><strong>Floats</strong> keep only their token. The digit layout in <code>extra</code> lets the conversion read the digits without scanning the token again, and only when the value is read.</li> <li><strong>Object members</strong> are the node of the key (a string) followed by the nodes of the value.</li> <li><strong>Navigation</strong> needs no pointers: the elements of an array or object follow its node, and the node after a value's subtree is <code>next</code> nodes further for an array or object, and the next node otherwise (<code>document_data::after</code>). Views step from element to element this way and skip whole subtrees in constant time.</li> <li><strong>Offsets</strong> are 32 bits wide, so a document is limited to 4294967279 bytes, 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes (a margin below 2^32 for positions one scanner step past the end of the text; <code>out_of_range.416</code>).</li> <li><strong>Source positions</strong> (<a href=../../api/macros/json_diagnostic_positions/ ><code>JSON_DIAGNOSTIC_POSITIONS</code></a>) are derived by <a href=../../api/basic_json_view/materialize/ ><code>materialize()</code></a> and cost almost nothing while parsing: the only work is storing the offset of the opening quote of a string with escapes in its <code>next</code>, which is otherwise unused. A scalar's range follows from <code>off</code> and its length, a string with escapes is scanned from its opening quote (<code>next</code>) to the closing one, and the end of an array or object is found by scanning from the end of its last element over whitespace, comments, and a trailing comma. <code>materialize()</code> hands these positions to the <abbr title="Simple API for XML">SAX</abbr> builder of <code>parse()</code> in place of its lexer.</li> <li><strong>Large objects</strong> (128 members or more) get a hash index for their keys after parsing (<a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp"><code>detail/view/object_index.hpp</code></a>): an open-addressing table whose slots hold the distance froLine truncated
    n0["0: object&lt;br&gt;len 1, next 5"]
    n1["1: key a"]
    n2["2: array&lt;br&gt;len 2, next 3"]
@@ -74,7 +74,7 @@
    e(["end"])
    n0 --&gt; n1 --&gt; n2 --&gt; n3 --&gt; n4 --&gt; e
    n0 -. next .-&gt; e
-    n2 -. next .-&gt; e</code></pre> <p class=nj-caption>The five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> in document order. Solid arrows lead from each node to the one after it; dotted arrows show where <code>next</code> leads from the object and the array, past their subtrees.</p> <table> <thead> <tr> <th>Node</th> <th><code>kind</code></th> <th><code>extra</code></th> <th><code>off</code></th> <th><code>len</code></th> <th><code>next</code></th> </tr> </thead> <tbody> <tr> <td>0</td> <td>1 (object)</td> <td>0</td> <td>0</td> <td>1</td> <td>5</td> </tr> <tr> <td>1</td> <td>3 (string)</td> <td>0</td> <td>2</td> <td>1</td> <td>0</td> </tr> <tr> <td>2</td> <td>2 (array)</td> <td>0</td> <td>6</td> <td>2</td> <td>3</td> </tr> <tr> <td>3</td> <td>6 (unsigned integer)</td> <td>0x0001</td> <td>7</td> <td>-</td> <td>-</td> </tr> <tr> <td>4</td> <td>7 (float)</td> <td>0x0101</td> <td>10</td> <td>3</td> <td>0</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of the five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code>. <code>off</code> is the byte offset in the text, and - marks the bytes 8-15 that hold the integer's value instead of <code>len</code> and <code>next</code>.</p> <p>All <code>flags</code> are 0. The integer's bytes 8-15 hold its value, 1; its <code>extra</code> says it has one digit. The float's <code>extra</code> says it has one integer and one fraction digit, and its <code>len</code> is that of the token <code>2.5</code>.</p> <p>Editable documents (<a href=../../api/json_editable_document/ ><code>json_editable_document</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit.hpp"><code>detail/view/edit.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit_storage.hpp"><code>detail/view/edit_storage.hpp</code></a>) never write the source text and never move or resize the parsed index, so views stay valid while the document is edited:</p> <ul> <li>A new scalar is written over its node. Its text (a string, or the token of a number as <code>dump()</code> writes it) goes to the edit buffer, which <code>flags</code> bits 0-1 then name.</li> <li>An array or object whose elements change gets the flag <em>moved</em> (bit 3): its elements then live in a separate sequence (a header node, then the entries), whose number is in <code>off</code>. The entries are links (<code>kind</code> 10), whose bytes 8-15 hold the address of the value's node, so values never move.</li> <li>A node written by an edit gets the flag <em>new</em> (bit 4): it has no position in the source text.</li> <li>A value that an entry of such a sequence links to gets the flag <em>linked</em> (bit 5): its extent in the parsed layout (<code>next</code>) no longer matters, so a scalar can replace an array or object there in place.</li> <li>Views of read-only documents compile without any of this: how views walk the index is a template parameter (<code>navigation&lt;Editable&gt;</code>).</li> </ul> <p>Images (<a href=../../api/basic_json_document/save/ ><code>save</code></a> and <a href=../../api/basic_json_document/load/ ><code>load</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp"><code>detail/view/image.hpp</code></a>) store the nodes as they are: a 64-byte header (the magic bytes <code>NJVI</code>, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since <code>load</code> rebuilds the indexes. So a change of the node layout is a change of the image format: it must raise <code>image_version</code>, and <code>load</code> then rejects images of other versions (<code>parse_error.116</code>) instead of misreading them.</p> <h2 id=input-adapters>Input adapters<a class=headerlink href=#input-adapters title="Permanent link">&para;</a></h2> <p>Input is read via <strong>input adapters</strong> that abstract a source. Every input adapter provides this interface:</p> <div class=highlight><pre><span></span><code><span class=c1>/// the type of the characters in the input</span>
+    n2 -. next .-&gt; e</code></pre> <p class=nj-caption>The five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> in document order. Solid arrows lead from each node to the one after it; dotted arrows show where <code>next</code> leads from the object and the array, past their subtrees.</p> <table> <thead> <tr> <th>Node</th> <th><code>kind</code></th> <th><code>extra</code></th> <th><code>off</code></th> <th><code>len</code></th> <th><code>next</code></th> </tr> </thead> <tbody> <tr> <td>0</td> <td>1 (object)</td> <td>0</td> <td>0</td> <td>1</td> <td>5</td> </tr> <tr> <td>1</td> <td>3 (string)</td> <td>0</td> <td>2</td> <td>1</td> <td>0</td> </tr> <tr> <td>2</td> <td>2 (array)</td> <td>0</td> <td>6</td> <td>2</td> <td>3</td> </tr> <tr> <td>3</td> <td>6 (unsigned integer)</td> <td>0x0001</td> <td>7</td> <td>-</td> <td>-</td> </tr> <tr> <td>4</td> <td>7 (float)</td> <td>0x0101</td> <td>10</td> <td>3</td> <td>0</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of the five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code>. <code>off</code> is the byte offset in the text, and - marks the bytes 8-15 that hold the integer's value instead of <code>len</code> and <code>next</code>.</p> <p>All <code>flags</code> are 0. The integer's bytes 8-15 hold its value, 1; its <code>extra</code> says it has one digit. The float's <code>extra</code> says it has one integer and one fraction digit, and its <code>len</code> is that of the token <code>2.5</code>.</p> <p>Editable documents (<a href=../../api/json_editable_document/ ><code>json_editable_document</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit.hpp"><code>detail/view/edit.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit_storage.hpp"><code>detail/view/edit_storage.hpp</code></a>) never write the source text and never move or resize the parsed index, so views stay valid while the document is edited:</p> <ul> <li>A new scalar is written over its node. Its text (a string, or the token of a number as <code>dump()</code> writes it) goes to the edit buffer, which <code>flags</code> bits 0-1 then name.</li> <li>An array or object whose elements change gets the flag <em>moved</em> (bit 3): its elements then live in a separate sequence (a header node, then the entries), whose number is in <code>off</code>. The entries are links (<code>kind</code> 10), whose bytes 8-15 hold the address of the value's node, so values never move.</li> <li>A node written by an edit gets the flag <em>new</em> (bit 4): it has no position in the source text.</li> <li>A value that an entry of such a sequence links to gets the flag <em>linked</em> (bit 5): its extent in the parsed layout (<code>next</code>) no longer matters, so a scalar can replace an array or object there in place.</li> <li>Views of read-only documents compile without any of this: how views walk the index is a template parameter (<code>navigation&lt;Editable&gt;</code>).</li> </ul> <p>Images (<a href=../../api/basic_json_document/save/ ><code>save</code></a> and <a href=../../api/basic_json_document/load/ ><code>load</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp"><code>detail/view/image.hpp</code></a>) store the nodes as they are: a 64-byte header (the magic bytes <code>NJVI</code>, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since <code>load</code> rebuilds the indexes. The flag <em>new</em> is kept, as these values have no position in the text. So a change of the node layout is a change of the image format: it must raise <code>image_version</code>, and <code>load</code> then rejects images of other versions (<code>parse_error.116</code>) instead of misreading them.</p> <h2 id=input-adapters>Input adapters<a class=headerlink href=#input-adapters title="Permanent link">&para;</a></h2> <p>Input is read via <strong>input adapters</strong> that abstract a source. Every input adapter provides this interface:</p> <div class=highlight><pre><span></span><code><span class=c1>/// the type of the characters in the input</span>
 <span class=k>using</span><span class=w> </span><span class=n>char_type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>...;</span>

 <span class=c1>/// read a single character; returns std::char_traits&lt;char_type&gt;::eof() at the end of the input</span>
@@ -138,4 +138,4 @@

 <span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=o>&gt;</span>
 <span class=kt>void</span><span class=w> </span><span class=n>from_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_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=n>T</span><span class=o>&amp;</span><span class=w> </span><span class=n>t</span><span class=p>);</span>
-</code></pre></div> <p>found by argument-dependent lookup. The library defines them for standard types in <code>detail/conversions</code>; users add them for their own types, see <a href=../../features/arbitrary_types/ >Arbitrary Type Conversions</a>. The <a href=../../features/macros/ >serialization macros</a> generate these functions.</p> <h2 id=additional-features>Additional features<a class=headerlink href=#additional-features title="Permanent link">&para;</a></h2> <ul> <li><a href=../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> (class <code>json_pointer</code>) addresses values inside a tree. It is also the basis of <a href=../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a>.</li> <li><a href=../../features/binary_formats/ >Binary formats</a> are read by <code>binary_reader</code> and written by <code>binary_writer</code>.</li> <li>A <a href=../../api/basic_json/json_base_class_t/ >custom base class</a> can add members to every <a href=../../api/basic_json/ ><code>basic_json</code></a> value.</li> <li><a href=../../features/macros/ >Serialization macros</a> generate <code>to_json</code> and <code>from_json</code> functions for user-defined types.</li> </ul> <h2 id=details-namespace>Details namespace<a class=headerlink href=#details-namespace title="Permanent link">&para;</a></h2> <p>Namespace <code>nlohmann::detail</code> contains all implementation details. It is not part of the public <abbr title="Application Programming Interface">API</abbr> and may change in any release. Besides the components above, it contains:</p> <ul> <li>type traits to detect the capabilities of user-defined types (<code>detail/meta/type_traits.hpp</code>),</li> <li>backports of C++14/17 features to C++11 (<code>detail/meta/cpp_future.hpp</code>), and</li> <li>helpers such as <code>string_concat</code> and <code>string_escape</code>.</li> </ul> <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/ ><code>basic_json</code></a> - the main class and all its member functions</li> <li><a href=../../api/adl_serializer/ ><code>adl_serializer</code></a> - customization point for type conversions</li> <li><a href=../../api/json_sax/ ><code>json_sax</code></a> - interface of the <abbr title="Simple API for XML">SAX</abbr> parser events</li> <li><a href=../../features/parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> Interface</a> - how to consume parser events without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - the flat node index that backs views and documents</li> <li><a href=../../features/types/template_parameters/ >Template Parameter Requirements</a> - the template parameters of basic_json</li> <li><a href=../../features/serialization/ >Serialization</a> - the output side of the library</li> <li><a href=../../features/namespace/ ><code>nlohmann</code> Namespace</a> - how the library namespace is structured</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../design_goals/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Design goals"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 Line truncated
+</code></pre></div> <p>found by argument-dependent lookup. The library defines them for standard types in <code>detail/conversions</code>; users add them for their own types, see <a href=../../features/arbitrary_types/ >Arbitrary Type Conversions</a>. The <a href=../../features/macros/ >serialization macros</a> generate these functions.</p> <h2 id=additional-features>Additional features<a class=headerlink href=#additional-features title="Permanent link">&para;</a></h2> <ul> <li><a href=../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> (class <code>json_pointer</code>) addresses values inside a tree. It is also the basis of <a href=../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a>.</li> <li><a href=../../features/binary_formats/ >Binary formats</a> are read by <code>binary_reader</code> and written by <code>binary_writer</code>.</li> <li>A <a href=../../api/basic_json/json_base_class_t/ >custom base class</a> can add members to every <a href=../../api/basic_json/ ><code>basic_json</code></a> value.</li> <li><a href=../../features/macros/ >Serialization macros</a> generate <code>to_json</code> and <code>from_json</code> functions for user-defined types.</li> </ul> <h2 id=details-namespace>Details namespace<a class=headerlink href=#details-namespace title="Permanent link">&para;</a></h2> <p>Namespace <code>nlohmann::detail</code> contains all implementation details. It is not part of the public <abbr title="Application Programming Interface">API</abbr> and may change in any release. Besides the components above, it contains:</p> <ul> <li>type traits to detect the capabilities of user-defined types (<code>detail/meta/type_traits.hpp</code>),</li> <li>backports of C++14/17 features to C++11 (<code>detail/meta/cpp_future.hpp</code>), and</li> <li>helpers such as <code>string_concat</code> and <code>string_escape</code>.</li> </ul> <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/ ><code>basic_json</code></a> - the main class and all its member functions</li> <li><a href=../../api/adl_serializer/ ><code>adl_serializer</code></a> - customization point for type conversions</li> <li><a href=../../api/json_sax/ ><code>json_sax</code></a> - interface of the <abbr title="Simple API for XML">SAX</abbr> parser events</li> <li><a href=../../features/parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> Interface</a> - how to consume parser events without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - the flat node index that backs views and documents</li> <li><a href=../../features/types/template_parameters/ >Template Parameter Requirements</a> - the template parameters of basic_json</li> <li><a href=../../features/serialization/ >Serialization</a> - the output side of the library</li> <li><a href=../../features/namespace/ ><code>nlohmann</code> Namespace</a> - how the library namespace is structured</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 28, 2026 19:24:49 UTC">October 28, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../design_goals/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Design goals"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 Line truncated
@@ -171,7 +171,7 @@ Layout of one 16-byte node of a JSON view index. Each row is 32 bits wide, and t
 | 2-3   | `extra` | `uint16_t` | numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0                                                                                                                                                                                       |
 | 4-7   | `off`   | `uint32_t` | where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object                                                                                                                                                             |
 | 8-11  | `len`   | `uint32_t` | strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements                                                                                                                                                                                                                                   |
-| 12-15 | `next`  | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself                                                                                                                                                                                                                                                                              |
+| 12-15 | `next`  | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself; strings with escapes: the position of the opening quote in the source plus one if the document was parsed with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md), or 0 if it was not; all other values: 0               |

 Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.

@@ -180,6 +180,7 @@ Fields of a node, by their byte offset within the 16-byte node. Integers use byt
 - **Object members** are the node of the key (a string) followed by the nodes of the value.
 - **Navigation** needs no pointers: the elements of an array or object follow its node, and the node after a value's subtree is `next` nodes further for an array or object, and the next node otherwise (`document_data::after`). Views step from element to element this way and skip whole subtrees in constant time.
 - **Offsets** are 32 bits wide, so a document is limited to 4294967279 bytes, 4 GiB minus 16 bytes (a margin below 2^32 for positions one scanner step past the end of the text; `out_of_range.416`).
+- **Source positions** ([`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md)) are derived by [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) and cost almost nothing while parsing: the only work is storing the offset of the opening quote of a string with escapes in its `next`, which is otherwise unused. A scalar's range follows from `off` and its length, a string with escapes is scanned from its opening quote (`next`) to the closing one, and the end of an array or object is found by scanning from the end of its last element over whitespace, comments, and a trailing comma. `materialize()` hands these positions to the SAX builder of `parse()` in place of its lexer.
 - **Large objects** (128 members or more) get a hash index for their keys after parsing ([`detail/view/object_index.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp)): an open-addressing table whose slots hold the distance from the object's node to a key's node, so that a lookup does not compare every key. Of duplicate keys the table leads to the first, as a linear search does. The object's `extra` holds the number of its table. Only 65,535 tables fit into `extra`; objects beyond them are searched linearly.

 For example, `{"a": [1, 2.5]}` becomes five nodes. Each node's elements follow it, and `next` leads from an array or object past its subtree:
@@ -219,7 +220,7 @@ Editable documents ([`json_editable_document`](https://json.nlohmann.me/api/json
 - A value that an entry of such a sequence links to gets the flag *linked* (bit 5): its extent in the parsed layout (`next`) no longer matters, so a scalar can replace an array or object there in place.
 - Views of read-only documents compile without any of this: how views walk the index is a template parameter (`navigation<Editable>`).

-Images ([`save`](https://json.nlohmann.me/api/basic_json_document/save/index.md) and [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md), [`detail/view/image.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp)) store the nodes as they are: a 64-byte header (the magic bytes `NJVI`, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since `load` rebuilds the indexes. So a change of the node layout is a change of the image format: it must raise `image_version`, and `load` then rejects images of other versions (`parse_error.116`) instead of misreading them.
+Images ([`save`](https://json.nlohmann.me/api/basic_json_document/save/index.md) and [`load`](https://json.nlohmann.me/api/basic_json_document/load/index.md), [`detail/view/image.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp)) store the nodes as they are: a 64-byte header (the magic bytes `NJVI`, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since `load` rebuilds the indexes. The flag *new* is kept, as these values have no position in the text. So a change of the node layout is a change of the image format: it must raise `image_version`, and `load` then rejects images of other versions (`parse_error.116`) instead of misreading them.

 ## Input adapters

@@ -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=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#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> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> 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=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.5Line truncated
+<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/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=../../../css/custom.css><link rel=stylesheet href=../../../css/brand.css><link rel=stylesheet href=../../../css/fig-sax.css><link rel=stylesheet href=../../../css/fig-jsonview.css><link rel=stylesheet href=../../../css/fig-exceptions.css><link rel=stylesheet href=../../../css/fig-pointer.css><link rel=stylesheet href=../../../css/fig-charts.css><link rel=stylesheet href=../../../css/fig-integration.css><link rel=stylesheet href=../../../css/fig-macros.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#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> <img src=../../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> 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=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.5Line truncated
@@ -100,6 +100,7 @@ These changes are part of the `develop` branch, but not of a release yet.
 - [`basic_json::patch_inplace`](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md): Added [`out_of_range.413`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range413) and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent in version 3.13.0 unreleased.
 - [`basic_json::patch_inplace`](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md): Added [`out_of_range.414`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range414) and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result in version 3.13.0 unreleased.
 - [`basic_json::patch_inplace`](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md): Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+- [`basic_json::patch_inplace`](https://json.nlohmann.me/api/basic_json/patch_inplace/index.md): Applying a JSON value as patch to itself (or, with `JSON_DIAGNOSTICS`, to a value stored inside it) no longer results in undefined behavior in version 3.13.0 unreleased.
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): Added `ignore_trailing_commas` in version 3.13.0 unreleased.
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): Added `tag_handler` in version 3.13.0 unreleased.
 - [`basic_json::sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md): Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
@@ -138,6 +139,7 @@ These changes are part of the `develop` branch, but not of a release yet.
 - [`basic_json::value`](https://json.nlohmann.me/api/basic_json/value/index.md): Overload 2: Support for keys convertible to `std::string_view` added in version 3.13.0 unreleased, consistently across the lookup functions.
 - [`basic_json::value`](https://json.nlohmann.me/api/basic_json/value/index.md): Overload 3: Extended to work with arrays in version 3.13.0 unreleased.
 - [`basic_json::value`](https://json.nlohmann.me/api/basic_json/value/index.md): Overload 3: Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of returning `default_value` for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0 unreleased, as it already did for longer ones.
+- [`json_pointer::operator/=`](https://json.nlohmann.me/api/json_pointer/operator_slasheq/index.md): Overload 1: Appending a JSON pointer to itself no longer results in undefined behavior in version 3.13.0 unreleased.
 - [`JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26`](https://json.nlohmann.me/api/macros/json_has_cpp_11/index.md): Added `JSON_HAS_CPP_26` in version 3.13.0 unreleased.
 - [`JSON_HAS_RANGES`](https://json.nlohmann.me/api/macros/json_has_ranges/index.md): Added the exclusions for libstdc++ < 11, Clang < 16 with libstdc++, libc++ < 16, and nvcc (CUDA) 12.0.x and 12.1.x in version 3.13.0 unreleased.
 - [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md): Also affects the conversion between `basic_json` specializations with different string types since version 3.13.0 unreleased.
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, converting your own C++ types, JSON Pointer/Patch/Merge Patch, binary formats, zero-copy views, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes, as well as for <code>json_document</code> and <code>json_view</code>.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p> </p>"},{"location":"api/is_json_view/","title":"nlohmann::is_json_view","text":"<p>Defined in header <code>&lt;nlohmann/json_view.hpp&gt;</code></p> <pre><code>template&lt;typename T&gt;\nstruct is_json_view;\n</code></pre> <p>A type trait: <code>is_json_view&lt;T&gt;::value</code> is <code>true</code> if <code>T</code> is a <code>basic_json_view</code> of any <code>BasicJsonType</code> and any <code>view_mode</code> -- <code>json_view</code>, <code>json_editable_view</code>, <code>ordered_json_view</code>, ... -- and <code>false</code> otherwise, for <code>basic_json</code> as well.</p> <p>It is meant for constraining templates that accept views, in particular a <code>from_json()</code> that should read views directly: <code>get&lt;T&gt;()</code> on a view calls a <code>from_json()</code> with the view only if that <code>from_json()</code> accepts views but not arbitrary types.</p>"},{"location":"api/is_json_view/#template-parameters","title":"Template parameters","text":"<code>T</code> the type to check (without cv-qualifiers or references)"},{"location":"api/is_json_view/#notes","title":"Notes","text":"<p>A view is recognized by its member type <code>basic_json_type</code> (a <code>basic_json</code> specialization) and its <code>materialize()</code> returning that type, so the trait needs no declaration of the view class.</p>"},{"location":"api/is_json_view/#examples","title":"Examples","text":"Example <p>The example below shows the trait, and a <code>from_json()</code> constrained to <code>json</code> values and views: <code>get&lt;T&gt;()</code> on a view reads the view directly.</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;type_traits&gt;\n#include &lt;nlohmann/json_view.hpp&gt;\n\nusing nlohmann::json;\n\nnamespace ns\n{\nstruct person\n{\n    std::string name;\n    int age = 0;\n};\n\n// reads json values and views (of any document type), but nothing else\ntemplate &lt; typename J, typename std::enable_if &lt; nlohmann::is_json_view&lt;J&gt;::value || std::is_same&lt;J, json&gt;::value, int &gt;::type = 0 &gt;\nvoid from_json(const J&amp; j, person&amp; p)\n{\n    p.name = j.at(\"name\").template get&lt;std::string&gt;();\n    p.age = j.at(\"age\").template get&lt;int&gt;();\n}\n} // namespace ns\n\nint main()\n{\n    std::cout &lt;&lt; std::boolalpha\n              &lt;&lt; nlohmann::is_json_view&lt;nlohmann::json_view&gt;::value &lt;&lt; ' '\n              &lt;&lt; nlohmann::is_json_view&lt;nlohmann::ordered_json_editable_view&gt;::value &lt;&lt; ' '\n              &lt;&lt; nlohmann::is_json_view&lt;json&gt;::value &lt;&lt; '\\n';\n\n    const nlohmann::json_document doc = nlohmann::json_document::parse(R\"({\"name\": \"Ada\", \"age\": 36})\");\n    const auto p = doc.root().get&lt;ns::person&gt;(); // reads the view, no json value is built\n    std::cout &lt;&lt; p.name &lt;&lt; ' ' &lt;&lt; p.age &lt;&lt; '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>true true false\nAda 36\n</code></pre>"},{"location":"api/is_json_view/#see-also","title":"See also","text":"<ul> <li>basic_json_view - a handle to one value of a document</li> <li>get - which conversions read the view directly</li> <li>view_mode - read-only or editable</li> <li>Writing generic code - functions and <code>from_json()</code> for views</li> </ul>"},{"location":"api/is_json_view/#version-history","title":"Version history","text":"<p>Added in version 3.13.0 unreleased.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json&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 Line truncated
+{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, converting your own C++ types, JSON Pointer/Patch/Merge Patch, binary formats, zero-copy views, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes, as well as for <code>json_document</code> and <code>json_view</code>.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p> </p>"},{"location":"api/is_json_view/","title":"nlohmann::is_json_view","text":"<p>Defined in header <code>&lt;nlohmann/json_view.hpp&gt;</code></p> <pre><code>template&lt;typename T&gt;\nstruct is_json_view;\n</code></pre> <p>A type trait: <code>is_json_view&lt;T&gt;::value</code> is <code>true</code> if <code>T</code> is a <code>basic_json_view</code> of any <code>BasicJsonType</code> and any <code>view_mode</code> -- <code>json_view</code>, <code>json_editable_view</code>, <code>ordered_json_view</code>, ... -- and <code>false</code> otherwise, for <code>basic_json</code> as well.</p> <p>It is meant for constraining templates that accept views, in particular a <code>from_json()</code> that should read views directly: <code>get&lt;T&gt;()</code> on a view calls a <code>from_json()</code> with the view only if that <code>from_json()</code> accepts views but not arbitrary types.</p>"},{"location":"api/is_json_view/#template-parameters","title":"Template parameters","text":"<code>T</code> the type to check (without cv-qualifiers or references)"},{"location":"api/is_json_view/#notes","title":"Notes","text":"<p>A view is recognized by its member type <code>basic_json_type</code> (a <code>basic_json</code> specialization) and its <code>materialize()</code> returning that type, so the trait needs no declaration of the view class.</p>"},{"location":"api/is_json_view/#examples","title":"Examples","text":"Example <p>The example below shows the trait, and a <code>from_json()</code> constrained to <code>json</code> values and views: <code>get&lt;T&gt;()</code> on a view reads the view directly.</p> <pre><code>#include &lt;iostream&gt;\n#include &lt;type_traits&gt;\n#include &lt;nlohmann/json_view.hpp&gt;\n\nusing nlohmann::json;\n\nnamespace ns\n{\nstruct person\n{\n    std::string name;\n    int age = 0;\n};\n\n// reads json values and views (of any document type), but nothing else\ntemplate &lt; typename J, typename std::enable_if &lt; nlohmann::is_json_view&lt;J&gt;::value || std::is_same&lt;J, json&gt;::value, int &gt;::type = 0 &gt;\nvoid from_json(const J&amp; j, person&amp; p)\n{\n    p.name = j.at(\"name\").template get&lt;std::string&gt;();\n    p.age = j.at(\"age\").template get&lt;int&gt;();\n}\n} // namespace ns\n\nint main()\n{\n    std::cout &lt;&lt; std::boolalpha\n              &lt;&lt; nlohmann::is_json_view&lt;nlohmann::json_view&gt;::value &lt;&lt; ' '\n              &lt;&lt; nlohmann::is_json_view&lt;nlohmann::ordered_json_editable_view&gt;::value &lt;&lt; ' '\n              &lt;&lt; nlohmann::is_json_view&lt;json&gt;::value &lt;&lt; '\\n';\n\n    const nlohmann::json_document doc = nlohmann::json_document::parse(R\"({\"name\": \"Ada\", \"age\": 36})\");\n    const auto p = doc.root().get&lt;ns::person&gt;(); // reads the view, no json value is built\n    std::cout &lt;&lt; p.name &lt;&lt; ' ' &lt;&lt; p.age &lt;&lt; '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>true true false\nAda 36\n</code></pre>"},{"location":"api/is_json_view/#see-also","title":"See also","text":"<ul> <li>basic_json_view - a handle to one value of a document</li> <li>get - which conversions read the view directly</li> <li>view_mode - read-only or editable</li> <li>Writing generic code - functions and <code>from_json()</code> for views</li> </ul>"},{"location":"api/is_json_view/#version-history","title":"Version history","text":"<p>Added in version 3.13.0 unreleased.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json&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 Line truncated