This commit is contained in:
nlohmann committed 2026-10-12 07:35:31 +00:00
1 parent 79119509a9
commit 22fba27145
555 files changed
+17342 -1394

No files matched your search

+3 -3
View File
@@ -1,4 +1,4 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/value/" rel="canonical"><link href=../update/ rel=prev><link href=../value_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>value - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonvalue class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> value </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <divLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/api/basic_json/value/" rel="canonical"><link href=../update/ rel=prev><link href=../value_t/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>value - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../../css/custom.css><script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#nlohmannbasic_jsonvalue class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> value </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <divLine truncated
<span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>ValueType</span><span class=o>&gt;</span>
<span class=n>ValueType</span><span class=w> </span><span class=n>value</span><span class=p>(</span><span class=k>const</span><span class=w> </span><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><span class=o>&amp;</span><span class=w> </span><span class=n>key</span><span class=p>,</span>
<span class=w> </span><span class=n>ValueType</span><span class=o>&amp;&amp;</span><span class=w> </span><span class=n>default_value</span><span class=p>)</span><span class=w> </span><span class=k>const</span><span class=p>;</span>
@@ -22,7 +22,7 @@
<span class=p>}</span><span class=w> </span><span class=k>catch</span><span class=p>(</span><span class=n>out_of_range</span><span class=p>)</span><span class=w> </span><span class=p>{</span>
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=n>default_value</span><span class=p>;</span>
<span class=p>}</span>
</code></pre></div></p> </li> </ol> <div class="admonition note"> <p class=admonition-title>Differences to <code>at</code> and <code>operator[]</code></p> <ul> <li>Unlike <a href=../at/ ><code>at</code></a>, this function does not throw if the given <code>key</code>/<code>ptr</code> was not found.</li> <li>Unlike <a href=../operator%5B%5D/ ><code>operator[]</code></a>, this function does not implicitly add an element to the position defined by <code>key</code>/<code>ptr</code> key. This function is furthermore also applicable to const objects.</li> </ul> </div> <div class="admonition note"> <p class=admonition-title>Integer keys</p> <p>Calling this function with an integer <code>key</code> argument (for example, <code class=highlight><span class=n>value</span><span class=p>(</span><span class=mi>0</span><span class=p>,</span><span class=w> </span><span class=mi>1</span><span class=p>)</span></code>) does not compile in C++11, where <code>object_comparator_t</code> is not transparent: such an argument would otherwise implicitly convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, cause undefined behavior when constructing a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> for the object key. To access an array element with a default value, use <a href=../at/ ><code>at</code></a> together with a <code class=highlight><span class=k>try</span></code>/<code class=highlight><span class=k>catch</span></code> block, or compare against <a href=../size/ ><code>size</code></a> instead.</p> </div> <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> <dt><code>ValueType</code></dt> <dd>type compatible to <abbr title="JavaScript Object Notation">JSON</abbr> values, for instance <code class=highlight><span class=kt>int</span></code> for <abbr title="JavaScript Object Notation">JSON</abbr> integer numbers, <code class=highlight><span class=kt>bool</span></code> for <abbr title="JavaScript Object Notation">JSON</abbr> booleans, or <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> types for <abbr title="JavaScript Object Notation">JSON</abbr> arrays. Note the type of the expected value at <code>key</code>/<code>ptr</code> and the default value <code>default_value</code> must be compatible.</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key of the element to access</dd> <dt><code>default_value</code> (in)</dt> <dd>the value to return if <code>key</code>/<code>ptr</code> found no value</dd> <dt><code>ptr</code> (in)</dt> <dd>a <abbr title="JavaScript Object Notation">JSON</abbr> pointer to the element to access</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>copy of the element at key <code>key</code> or <code>default_value</code> if <code>key</code> is not found</li> <li>copy of the element at key <code>key</code> or <code>default_value</code> if <code>key</code> is not found</li> <li>copy of the element at <abbr title="JavaScript Object Notation">JSON</abbr> Pointer <code>ptr</code> or <code>default_value</code> if no value for <code>ptr</code> is found</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value.</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_error302><code>type_error.302</code></a> if <code>default_value</code> does not match the type of the value at <code>key</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error306><code>type_error.306</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in that case, using <code>value()</code> with a key makes no sense.</li> </ul> </li> <li>See 1.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error302><code>type_error.302</code></a> if <code>default_value</code> does not match the type of the value at <code>ptr</code></li> <li>Throws <a href=Line truncated
</code></pre></div></p> </li> </ol> <div class="admonition note"> <p class=admonition-title>Differences to <code>at</code> and <code>operator[]</code></p> <ul> <li>Unlike <a href=../at/ ><code>at</code></a>, this function does not throw if the given <code>key</code>/<code>ptr</code> was not found.</li> <li>Unlike <a href=../operator%5B%5D/ ><code>operator[]</code></a>, this function does not implicitly add an element to the position defined by <code>key</code>/<code>ptr</code> key. This function is furthermore also applicable to const objects.</li> </ul> </div> <div class="admonition note"> <p class=admonition-title>Integer keys</p> <p>Calling this function with an integer <code>key</code> argument (for example, <code class=highlight><span class=n>value</span><span class=p>(</span><span class=mi>0</span><span class=p>,</span><span class=w> </span><span class=mi>1</span><span class=p>)</span></code>) does not compile in C++11, where <code>object_comparator_t</code> is not transparent: such an argument would otherwise implicitly convert to a null <code class=highlight><span class=k>const</span><span class=w> </span><span class=kt>char</span><span class=o>*</span></code> and, from there, cause undefined behavior when constructing a <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>string</span></code> for the object key. To access an array element with a default value, use <a href=../at/ ><code>at</code></a> together with a <code class=highlight><span class=k>try</span></code>/<code class=highlight><span class=k>catch</span></code> block, or compare against <a href=../size/ ><code>size</code></a> instead.</p> </div> <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> <dt><code>ValueType</code></dt> <dd>type compatible to <abbr title="JavaScript Object Notation">JSON</abbr> values, for instance <code class=highlight><span class=kt>int</span></code> for <abbr title="JavaScript Object Notation">JSON</abbr> integer numbers, <code class=highlight><span class=kt>bool</span></code> for <abbr title="JavaScript Object Notation">JSON</abbr> booleans, or <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span></code> types for <abbr title="JavaScript Object Notation">JSON</abbr> arrays. Note the type of the expected value at <code>key</code>/<code>ptr</code> and the default value <code>default_value</code> must be compatible.</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>key</code> (in)</dt> <dd>key of the element to access</dd> <dt><code>default_value</code> (in)</dt> <dd>the value to return if <code>key</code>/<code>ptr</code> found no value</dd> <dt><code>ptr</code> (in)</dt> <dd>a <abbr title="JavaScript Object Notation">JSON</abbr> pointer to the element to access</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <ol> <li>copy of the element at key <code>key</code> or <code>default_value</code> if <code>key</code> is not found</li> <li>copy of the element at key <code>key</code> or <code>default_value</code> if <code>key</code> is not found</li> <li>copy of the element at <abbr title="JavaScript Object Notation">JSON</abbr> Pointer <code>ptr</code> or <code>default_value</code> if no value for <code>ptr</code> is found</li> </ol> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes to any <abbr title="JavaScript Object Notation">JSON</abbr> value.</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_error302><code>type_error.302</code></a> if <code>default_value</code> does not match the type of the value at <code>key</code></li> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error306><code>type_error.306</code></a> if the <abbr title="JavaScript Object Notation">JSON</abbr> value is not an object; in that case, using <code>value()</code> with a key makes no sense.</li> </ul> </li> <li>See 1.</li> <li>The function can throw the following exceptions:<ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptiontype_error302><code>type_error.302</code></a> if <code>default_value</code> does not match the type of the value at <code>ptr</code></li> <li>Throws <a href=Line truncated
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<span class=k>using</span><span class=w> </span><span class=n>json</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
@@ -171,4 +171,4 @@
<span class=p>}</span>
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><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>.</span><span class=kc>t</span><span class=err>ype_error.</span><span class=mi>302</span><span class=p>]</span><span class=w> </span><span class=kc>t</span><span class=err>ype</span><span class=w> </span><span class=err>mus</span><span class=kc>t</span><span class=w> </span><span class=err>be</span><span class=w> </span><span class=kc>nu</span><span class=err>mber</span><span class=p>,</span><span class=w> </span><span class=err>bu</span><span class=kc>t</span><span class=w> </span><span class=err>is</span><span class=w> </span><span class=err>s</span><span class=kc>tr</span><span class=err>i</span><span class=kc>n</span><span class=err>g</span>
<span class=p>[</span><span class=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>.</span><span class=kc>t</span><span class=err>ype_error.</span><span class=mi>306</span><span class=p>]</span><span class=w> </span><span class=err>ca</span><span class=kc>nn</span><span class=err>o</span><span class=kc>t</span><span class=w> </span><span class=err>use</span><span class=w> </span><span class=err>value()</span><span class=w> </span><span class=err>wi</span><span class=kc>t</span><span class=err>h</span><span class=w> </span><span class=err>s</span><span class=kc>tr</span><span class=err>i</span><span class=kc>n</span><span class=err>g</span>
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li>see <a href=../at/ ><code>at</code></a> for access by reference with range checking</li> <li>see <a href=../operator%5B%5D/ ><code>operator[]</code></a> for unchecked access by reference</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. Changed parameter <code>default_value</code> type from <code>const ValueType&amp;</code> to <code>ValueType&amp;&amp;</code> in version 3.11.0. Deleted overload for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> <li>Added in version 3.11.0. Made <code>ValueType</code> the first template parameter in version 3.11.2. 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 consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../find/ ><code>find</code></a>, and other lookup functions.</li> <li>Added in version 2.0.2. Extended to work with arrays 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>, including fixing an issue where resolving <code>ptr</code> through an array unexpectedly threw <code>out_of_range</code> instead of returning the resolved element (or <code>default_value</code>, as documented).</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 4, 2026 09:46:32 UTC">October 4, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-Line truncated
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li>see <a href=../at/ ><code>at</code></a> for access by reference with range checking</li> <li>see <a href=../operator%5B%5D/ ><code>operator[]</code></a> for unchecked access by reference</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. Changed parameter <code>default_value</code> type from <code>const ValueType&amp;</code> to <code>ValueType&amp;&amp;</code> in version 3.11.0. Deleted overload for integral key types added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span> to reject such calls at compile time instead of causing undefined behavior at runtime.</li> <li>Added in version 3.11.0. Made <code>ValueType</code> the first template parameter in version 3.11.2. 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 consistently accept <code>std::string_view</code>-convertible keys, as already supported by <a href=../operator%5B%5D/ ><code>operator[]</code></a>, <a href=../at/ ><code>at</code></a>, <a href=../find/ ><code>find</code></a>, and other lookup functions.</li> <li>Added in version 2.0.2. Extended to work with arrays 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>, including fixing an issue where resolving <code>ptr</code> through an array unexpectedly threw <code>out_of_range</code> instead of returning the resolved element (or <code>default_value</code>, as documented). Throws <a href=../../../home/exceptions/#jsonexceptionparse_error109><code>parse_error.109</code></a> instead of returning <code>default_value</code> for a one-character array index that is not a digit (e.g., <code>/x</code>) in version 3.13.0, 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 11, 2026 06:22:10 UTC">October 11, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 6Line truncated
+5 -1
View File
@@ -98,6 +98,10 @@ Strong guarantee: if an exception is thrown, there are no changes to any JSON va
## Notes
`null` members are not missing
The default value is used only if the key (or JSON Pointer) does not exist. A member that exists but is `null` is converted like any other value, so `j.value("k", 0)` throws a [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if `"k"` is `null`. See [Access with default value](https://json.nlohmann.me/features/element_access/default_value/index.md) for alternatives.
Return type
The value function is a template, and the return type of the function is determined by the type of the provided default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit unsigned integer. We get exactly that value when using [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md). However, when we call `value` and provide `0` as default value, then `-1` is returned. This occurs, because `0` has type `int` which overflows when handling the value `18446744073709551615`.
@@ -328,4 +332,4 @@ Output:
1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0. Deleted overload for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.
1. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`find`](https://json.nlohmann.me/api/basic_json/find/index.md), and other lookup functions.
1. Added in version 2.0.2. Extended to work with arrays in version 3.13.0 unreleased, including fixing an issue where resolving `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or `default_value`, as documented).
1. Added in version 2.0.2. Extended to work with arrays in version 3.13.0 unreleased, including fixing an issue where resolving `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or `default_value`, as documented). Throws [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) instead of returning `default_value` for a one-character array index that is not a digit (e.g., `/x`) in version 3.13.0, as it already did for longer ones.