This commit is contained in:
nlohmann committed 2026-10-27 12:14:00 +00:00
1 parent b36f8a9821
commit 11a863958e
1180 files changed
+14211 -6025

No files matched your search

+5 -5
View File
@@ -1,7 +1,7 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/parser_callbacks/" rel="canonical"><link href=../parse_exceptions/ rel=prev><link href=../sax_interface/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parser Callbacks - 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=#parser-callbacks 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> Parser Callbacks </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 14Line truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/features/parsing/parser_callbacks/" rel="canonical"><link href=../parse_exceptions/ rel=prev><link href=../sax_interface/ rel=next><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Parser Callbacks - 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=#parser-callbacks 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> Parser Callbacks </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 Line truncated
<span class=k>using</span><span class=w> </span><span class=n>parser_callback_t</span><span class=w> </span><span class=o>=</span>
<span class=w> </span><span class=n>std</span><span class=o>::</span><span class=n>function</span><span class=o>&lt;</span><span class=kt>bool</span><span class=p>(</span><span class=kt>int</span><span class=w> </span><span class=n>depth</span><span class=p>,</span><span class=w> </span><span class=n>parse_event_t</span><span class=w> </span><span class=n>event</span><span class=p>,</span><span class=w> </span><span class=n>BasicJsonType</span><span class=o>&amp;</span><span class=w> </span><span class=n>parsed</span><span class=p>)</span><span class=o>&gt;</span><span class=p>;</span>
</code></pre></div> <h2 id=callback-event-types>Callback event types<a class=headerlink href=#callback-event-types title="Permanent link">&para;</a></h2> <p>We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values of the parameters <code>depth</code>, <code>event</code>, and <code>parsed</code>.</p> <table> <thead> <tr> <th>parameter <code>event</code></th> <th>description</th> <th>parameter <code>depth</code></th> <th>parameter <code>parsed</code></th> </tr> </thead> <tbody> <tr> <td><code>parse_event_t::object_start</code></td> <td>the parser read <code>{</code> and started to process a <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> value with type discarded</td> </tr> <tr> <td><code>parse_event_t::key</code></td> <td>the parser read a key of a value in an object</td> <td>depth of the currently parsed <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> string containing the key</td> </tr> <tr> <td><code>parse_event_t::object_end</code></td> <td>the parser read <code>}</code> and finished processing a <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> object</td> </tr> <tr> <td><code>parse_event_t::array_start</code></td> <td>the parser read <code>[</code> and started to process a <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> value with type discarded</td> </tr> <tr> <td><code>parse_event_t::array_end</code></td> <td>the parser read <code>]</code> and finished processing a <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> array</td> </tr> <tr> <td><code>parse_event_t::value</code></td> <td>the parser finished reading a <abbr title="JavaScript Object Notation">JSON</abbr> value</td> <td>depth of the value</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> value</td> </tr> </tbody> </table> <details class=example> <summary>Example: sequence of callback events</summary> <p>When parsing the following <abbr title="JavaScript Object Notation">JSON</abbr> text,</p> <div class=highlight><pre><span></span><code><span class=p>{</span>
</code></pre></div> <h2 id=callback-event-types>Callback event types<a class=headerlink href=#callback-event-types title="Permanent link">&para;</a></h2> <p>We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values of the parameters <code>depth</code>, <code>event</code>, and <code>parsed</code>.</p> <table> <thead> <tr> <th>parameter <code>event</code></th> <th>description</th> <th>parameter <code>depth</code></th> <th>parameter <code>parsed</code></th> </tr> </thead> <tbody> <tr> <td><code>parse_event_t::object_start</code></td> <td>the parser read <code>{</code> and started to process a <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> value with type discarded</td> </tr> <tr> <td><code>parse_event_t::key</code></td> <td>the parser read a key of a value in an object</td> <td>depth of the currently parsed <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> string containing the key</td> </tr> <tr> <td><code>parse_event_t::object_end</code></td> <td>the parser read <code>}</code> and finished processing a <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> object</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> object</td> </tr> <tr> <td><code>parse_event_t::array_start</code></td> <td>the parser read <code>[</code> and started to process a <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>a <abbr title="JavaScript Object Notation">JSON</abbr> value with type discarded</td> </tr> <tr> <td><code>parse_event_t::array_end</code></td> <td>the parser read <code>]</code> and finished processing a <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>depth of the parent of the <abbr title="JavaScript Object Notation">JSON</abbr> array</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> array</td> </tr> <tr> <td><code>parse_event_t::value</code></td> <td>the parser finished reading a <abbr title="JavaScript Object Notation">JSON</abbr> value</td> <td>depth of the value</td> <td>the parsed <abbr title="JavaScript Object Notation">JSON</abbr> value</td> </tr> </tbody> </table> <div class=nj-fig-wrap> <p><svg class="nj-fig nj-fig--cb" viewbox="0 0 480 262" role=img aria-labelledby=fig-cb-title xmlns=http://www.w3.org/2000/svg> <title id=fig-cb-title>Example of the parse events a callback sees for the J&#8203;SON text {&quot;name&quot;: &quot;Berlin&quot;, &quot;location&quot;: [52.519444, 13.406667]}: object_start after the opening brace, key after each key, array_start after the opening bracket, value after each value, array_end after the closing bracket, and object_end after the closing brace. Every array and object also produces a value event when it is complete.</title> <text class=fg-h x=16 y=28>J&#8203;SON to parse</text> <text class=fg-h x=320 y=28>callback events</text> <text class=fg-code x=16 y=74 xml:space=preserve>{</text> <circle class=cb-os cx=35.6 cy=69 r=5.5 /> <text class=fg-code x=35.2 y=102 xml:space=preserve>&quot;name&quot;</text> <circle class=cb-k cx=102.8 cy=97 r=5.5 /> <text class=fg-code x=112.8 y=102 xml:space=preserve>: &quot;Berlin&quot;</text> <circle class=cb-v cx=218.8 cy=97 r=5.5 /> <text class=fg-code x=228.8 y=102 xml:space=preserve>,</text> <text class=fg-code x=35.2 y=130 xml:space=preserve>&quot;location&quot;</text> <circle class=cb-k cx=141.2 cy=125 r=5.5 /> <text class=fg-code x=151.2 y=130 xml:space=preserve>: [</text> <circle class=cb-as cx=190 cy=125 r=5.5 /> <text class=fg-code x=54.4 y=158 xml:space=preserve>52.519444</text> <circle class=cb-v cx=150.8 cy=153 r=5.5 /> <text class=fg-code x=160.8 y=158 xml:space=preserve>,</text> <text class=fg-code x=54.4 y=186 xml:space=preserve>13.406667</text> <circle class=cb-v cx=150.8 cy=181 r=5.5 /> <text class=fg-code x=35.2 y=214 xml:space=preserve>]</text> <circle class=cb-ae cx=54.8 cy=209 r=5.5 /> <circle class=cb-v cx=74.8 cy=209 r=5.5 /> <text class=fg-code x=16 y=242 xml:space=preserve>}</text> <circle class=cb-oe cx=35.6 cy=237 r=5.5 /> <circle class=cb-v cx=55.6 cy=237 r=5.5 /> <circle class=cb-os cx=327 cy=69 r=6 /> <text class="fg-code fg-leg" x=344 y=74>object_start</text> <circle class=cb-k cx=327 cy=99 r=6 /> <text class="fg-code fg-leg" x=344 y=104>key</text> <circle class=cb-oe cx=327 cy=129 r=6 /> <text class="fg-code fg-leg" x=344 y=134>object_end</text> <circle class=cb-as cx=327 cy=159 r=6 /> <text class="fg-code fg-leg" x=344 y=164>array_start</text> <circle class=cb-ae cx=327 cy=189 r=6 /> <text class="fg-code fg-leg" xLine truncated
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"Berlin"</span><span class=p>,</span>
<span class=w> </span><span class=nt>"location"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
<span class=w> </span><span class=mf>52.519444</span><span class=p>,</span>
@@ -90,7 +90,7 @@
<span class=w> </span><span class=nt>"Width"</span><span class=p>:</span><span class=w> </span><span class=mi>800</span>
<span class=w> </span><span class=p>}</span>
<span class=p>}</span>
</code></pre></div> </details> <h2 id=recipe-rejecting-duplicate-object-keys>Recipe: rejecting duplicate object keys<a class=headerlink href=#recipe-rejecting-duplicate-object-keys title="Permanent link">&para;</a></h2> <p>The <abbr title="JavaScript Object Notation">JSON</abbr> specification leaves the handling of objects with repeated keys up to the implementation. As described in <a href=../../../api/basic_json/object_t/#behavior><code>object_t</code></a>, it is unspecified which value for a repeated key ends up in the resulting <code class=highlight><span class=n>json</span></code> value -- once parsing has produced that value, the duplicate is already gone, because object storage maps each key to a single value. If duplicate keys should instead be treated as an error, a parser callback can detect them while the object is still being read, before that ambiguity ever applies.</p> <details class=example> <summary>Example: reject duplicate object keys</summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
</code></pre></div> </details> <h2 id=recipe-rejecting-duplicate-object-keys>Recipe: rejecting duplicate object keys<a class=headerlink href=#recipe-rejecting-duplicate-object-keys title="Permanent link">&para;</a></h2> <p>The <abbr title="JavaScript Object Notation">JSON</abbr> specification leaves the handling of objects with repeated keys up to the implementation. As described in <a href=../../../api/basic_json/object_t/#behavior><code>object_t</code></a>, it is unspecified which value for a repeated key ends up in the resulting <code class=highlight><span class=n>json</span></code> value — once parsing has produced that value, the duplicate is already gone, because object storage maps each key to a single value. If duplicate keys should instead be treated as an error, a parser callback can detect them while the object is still being read, before that ambiguity ever applies.</p> <details class=example> <summary>Example: reject duplicate object keys</summary> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;stdexcept&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;string&gt;</span>
@@ -153,7 +153,7 @@
<span class=p>}</span>
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=nt>"one"</span><span class=p>:</span><span class=mi>1</span><span class=p>,</span><span class=nt>"two"</span><span class=p>:</span><span class=mi>2</span><span class=p>}</span>
<span class=err>duplica</span><span class=kc>te</span><span class=w> </span><span class=err>JSON</span><span class=w> </span><span class=err>objec</span><span class=kc>t</span><span class=w> </span><span class=err>key</span><span class=p>:</span><span class=w> </span><span class=err>o</span><span class=kc>ne</span>
</code></pre></div> </details> <p>This approach has three limitations:</p> <ul> <li>The depth-indexed bookkeeping must account for the fact that <code>object_start</code> reports the depth of the <em>parent</em> of the object, while the <code>key</code> events inside that object are reported one depth deeper (see the event table above); it is easy to get this off by one for nested objects.</li> <li>The thrown exception cannot carry a <code>parse_error</code>-style byte offset, because position tracking only exists inside the parser and lexer, not at the callback layer.</li> <li>The exception only names the repeated key, not where it occurs in the document. Reporting its full path requires maintaining a stack of the enclosing keys and array indices in the callback as well.</li> </ul> <p>A <a href=../sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> does not lift the position limitation: its <code>key</code> function receives no position either -- only <code>parse_error</code> is passed the byte position.</p> <h2 id=recipe-streaming-a-large-homogeneous-array>Recipe: streaming a large homogeneous array<a class=headerlink href=#recipe-streaming-a-large-homogeneous-array title="Permanent link">&para;</a></h2> <p>A common use case is a huge top-level array of many similarly-shaped objects, too large to hold entirely in memory as a <code class=highlight><span class=n>json</span></code> value. A parser callback can hand off each completed element to a user function and then discard it, so memory usage stays bounded by a single element (plus the not-yet-parsed tail of the input) rather than the whole document. Since the top-level array's <code>array_start</code>/<code>array_end</code> are reported at <code>depth == 0</code> (its parent is the document root), the object elements it contains are reported at <code>depth == 1</code>:</p> <details class=example> <summary>Example: stream a large top-level array</summary> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>input</span><span class=p>(</span><span class=s>"large_array.json"</span><span class=p>);</span>
</code></pre></div> </details> <p>This approach has three limitations:</p> <ul> <li>The depth-indexed bookkeeping must account for the fact that <code>object_start</code> reports the depth of the <em>parent</em> of the object, while the <code>key</code> events inside that object are reported one depth deeper (see the event table above); it is easy to get this off by one for nested objects.</li> <li>The thrown exception cannot carry a <code>parse_error</code>-style byte offset, because position tracking only exists inside the parser and lexer, not at the callback layer.</li> <li>The exception only names the repeated key, not where it occurs in the document. Reporting its full path requires maintaining a stack of the enclosing keys and array indices in the callback as well.</li> </ul> <p>A <a href=../sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> does not lift the position limitation: its <code>key</code> function receives no position either — only <code>parse_error</code> is passed the byte position.</p> <h2 id=recipe-streaming-a-large-homogeneous-array>Recipe: streaming a large homogeneous array<a class=headerlink href=#recipe-streaming-a-large-homogeneous-array title="Permanent link">&para;</a></h2> <p>A common use case is a huge top-level array of many similarly-shaped objects, too large to hold entirely in memory as a <code class=highlight><span class=n>json</span></code> value. A parser callback can hand off each completed element to a user function and then discard it, so memory usage stays bounded by a single element (plus the not-yet-parsed tail of the input) rather than the whole document. Since the top-level array's <code>array_start</code>/<code>array_end</code> are reported at <code>depth == 0</code> (its parent is the document root), the object elements it contains are reported at <code>depth == 1</code>:</p> <details class=example> <summary>Example: stream a large top-level array</summary> <div class=highlight><pre><span></span><code><span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>input</span><span class=p>(</span><span class=s>"large_array.json"</span><span class=p>);</span>
<span class=k>auto</span><span class=w> </span><span class=n>callback</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>[](</span><span class=kt>int</span><span class=w> </span><span class=n>depth</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_event_t</span><span class=w> </span><span class=n>event</span><span class=p>,</span><span class=w> </span><span class=n>json</span><span class=o>&amp;</span><span class=w> </span><span class=n>parsed</span><span class=p>)</span><span class=w> </span><span class=o>-&gt;</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=p>{</span>
<span class=w> </span><span class=k>if</span><span class=w> </span><span class=p>(</span><span class=n>depth</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=mi>1</span><span class=w> </span><span class=o>&amp;&amp;</span><span class=w> </span><span class=n>event</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse_event_t</span><span class=o>::</span><span class=n>object_end</span><span class=p>)</span><span class=w> </span><span class=p>{</span>
@@ -174,4 +174,4 @@
<span class=p>};</span>
<span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>input</span><span class=p>,</span><span class=w> </span><span class=n>callback</span><span class=p>);</span>
</code></pre></div> </details> <!-- 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 2, 2026 09:32:15 UTC">October 2, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.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="M162.7 210c-1.8 3.3-25.2 44.4-70.1 123.5-4.9 8.3-10.8 12.5-17.7 12.5H9.8c-7.7 0-12.1-7.5-8.5-14.4l69-121.3q.3 0 0-.3l-43.9-75.6c-4.3-7.8.3-14.1 8.5-14.1H100c7.3 0 13.3 4.1 18 12.2zM382.6 46.1l-144 253v.3L330.2 466c3.9 7.1.2 14.1-8.5 14.1h-65.2c-7.6 0-13.6-4-18-12.2l-92.4-168.5c3.3-5.8 51.5-90.8 144.Line truncated
</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../ >Parsing</a> - overview of the parsing functions</li> <li><a href=../sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> Interface</a> - guide to event-based parsing</li> <li><a href=../../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../../api/basic_json/parser_callback_t/ ><code>parser_callback_t</code></a> - callback function type for the parser</li> <li><a href=../../../api/basic_json/parse_event_t/ ><code>parse_event_t</code></a> - enumeration of parser events</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=../parse_exceptions/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Parsing and Exceptions"> <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> Parsing and Exceptions </div> </div> </a> <a href=../sax_interface/ class="md-footer__link md-footer__link--next" aria-label="Next: SAX Interface"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> SAX Interface </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-Line truncated
+12 -2
View File
@@ -25,6 +25,8 @@ We distinguish six scenarios (determined by the event type) in which the callbac
| `parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array |
| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
Each coloured dot marks where the parser reports a `parse_event_t` event while reading the JSON text on the left; the legend on the right names the event per colour.
Example: sequence of callback events
When parsing the following JSON text,
@@ -160,7 +162,7 @@ Output:
## Recipe: rejecting duplicate object keys
The JSON specification leaves the handling of objects with repeated keys up to the implementation. As described in [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/#behavior), it is unspecified which value for a repeated key ends up in the resulting `json` value -- once parsing has produced that value, the duplicate is already gone, because object storage maps each key to a single value. If duplicate keys should instead be treated as an error, a parser callback can detect them while the object is still being read, before that ambiguity ever applies.
The JSON specification leaves the handling of objects with repeated keys up to the implementation. As described in [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/#behavior), it is unspecified which value for a repeated key ends up in the resulting `json` value — once parsing has produced that value, the duplicate is already gone, because object storage maps each key to a single value. If duplicate keys should instead be treated as an error, a parser callback can detect them while the object is still being read, before that ambiguity ever applies.
Example: reject duplicate object keys
@@ -241,7 +243,7 @@ This approach has three limitations:
- The thrown exception cannot carry a `parse_error`-style byte offset, because position tracking only exists inside the parser and lexer, not at the callback layer.
- The exception only names the repeated key, not where it occurs in the document. Reporting its full path requires maintaining a stack of the enclosing keys and array indices in the callback as well.
A [SAX interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) does not lift the position limitation: its `key` function receives no position either -- only `parse_error` is passed the byte position.
A [SAX interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) does not lift the position limitation: its `key` function receives no position either — only `parse_error` is passed the byte position.
## Recipe: streaming a large homogeneous array
@@ -283,3 +285,11 @@ auto callback = [](int depth, json::parse_event_t /*event*/, json& /*parsed*/) -
json::parse(input, callback);
```
## See also
- [Parsing](https://json.nlohmann.me/features/parsing/index.md) - overview of the parsing functions
- [SAX Interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) - guide to event-based parsing
- [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
- [`parser_callback_t`](https://json.nlohmann.me/api/basic_json/parser_callback_t/index.md) - callback function type for the parser
- [`parse_event_t`](https://json.nlohmann.me/api/basic_json/parse_event_t/index.md) - enumeration of parser events