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.