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

+53 -7
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/home/architecture/" rel="canonical"><link href=../design_goals/ rel=prev><link href=../customers/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Architecture - 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=#architecture 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> Architecture </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-seaLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/home/architecture/" rel="canonical"><link href=../design_goals/ rel=prev><link href=../customers/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.7.7"><title>Architecture - 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=#architecture 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> Architecture </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5Line truncated
input[/"input&lt;br&gt;(string, stream,&lt;br&gt;iterator range, file)"/]
ia["input adapter"]
lexer["lexer"]
@@ -17,7 +17,7 @@
sax --&gt; value
value --&gt; serializer --&gt; oa
value --&gt; bwriter --&gt; oa
oa --&gt; output</code></pre> <ul> <li><strong><abbr title="JavaScript Object Notation">JSON</abbr> text</strong> is read by an <a href=#input-adapters>input adapter</a>, tokenized by the lexer, and turned into <abbr title="Simple API for XML">SAX</abbr> events by the parser.</li> <li><strong>Binary formats</strong> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>) are read by an input adapter and turned into the same <abbr title="Simple API for XML">SAX</abbr> events by the <code>binary_reader</code>.</li> <li>A <a href=#sax-interface><abbr title="Simple API for XML">SAX</abbr> consumer</a> receives the events. The one used by <a href=../../api/basic_json/parse/ ><code>parse</code></a> builds a <code>basic_json</code> value tree.</li> <li>The <code>serializer</code> (<abbr title="JavaScript Object Notation">JSON</abbr> text) or the <code>binary_writer</code> (binary formats) writes a value tree to an <a href=#output-adapters>output adapter</a>.</li> </ul> <h2 id=source-layout>Source layout<a class=headerlink href=#source-layout title="Permanent link">&para;</a></h2> <p>The public headers are in <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code></a>:</p> <ul> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json.hpp"><code>json.hpp</code></a> defines class <a href=../../api/basic_json/ ><code>basic_json</code></a>.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp"><code>json_fwd.hpp</code></a> contains forward declarations.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/adl_serializer.hpp"><code>adl_serializer.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/byte_container_with_subtype.hpp"><code>byte_container_with_subtype.hpp</code></a>, and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/ordered_map.hpp"><code>ordered_map.hpp</code></a> define <a href=../../api/adl_serializer/ ><code>adl_serializer</code></a>, <a href=../../api/byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a>, and <a href=../../api/ordered_map/ ><code>ordered_map</code></a>.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_view.hpp"><code>json_view.hpp</code></a> is a separate, optional header that defines <a href=../../api/basic_json_document/ ><code>basic_json_document</code></a> and <a href=../../api/basic_json_view/ ><code>basic_json_view</code></a>, a flat-index, read-only, non-owning way to look at a parsed <abbr title="JavaScript Object Notation">JSON</abbr> text; see <a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a>. It builds on <code>json.hpp</code> internals (it requires the same library version) and has its own <code>detail/view/</code> subdirectory.</li> </ul> <p>Everything else lives in <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann/detail"><code>detail/</code></a> and namespace <code>nlohmann::detail</code>, which is not part of the public <abbr title="Application Programming Interface">API</abbr>. Paths below are relative to <code>include/nlohmann</code>.</p> <table> <thead> <tr> <th>Component</th> <th>Location</th> </tr> </thead> <tbody> <tr> <td>Value type enumeration</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/value_t.hpp"><code>detail/value_t.hpp</code></a></td> </tr> <tr> <td>Input adapters</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/input_adapters.hpp"><code>detail/input/input_adapters.hpp</code></a></td> </tr> <tr> <td>Lexer</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/lexer.hpp"><code>detail/input/lexer.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/number_parse.hpp"><code>detail/input/number_parse.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/string_scan.hpp"><code>detail/input/string_scan.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/simd_scan.hpp"><code>detail/input/simd_scan.hpp</code></a></td> </tr> <tr> <td>Parser</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/parser.hpp"><code>detail/input/parser.hpp</code></a></td> </tr> <tr> <td><abbr title="Simple API for XML">SAX</abbr> interface and <abbr title="Document Object Model">DOM</abbr> builders</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/json_sax.hpp"><code>detail/input/json_sax.hpp</code><Line truncated
oa --&gt; output</code></pre> <p class=nj-caption>Data flow through the library: input runs left to right through an input adapter and the lexer and parser (<abbr title="JavaScript Object Notation">JSON</abbr> text) or the <code>binary_reader</code> (binary formats) into <abbr title="Simple API for XML">SAX</abbr> events, which build the value tree; the <code>serializer</code> or the <code>binary_writer</code> writes the tree to an output adapter.</p> <ul> <li><strong><abbr title="JavaScript Object Notation">JSON</abbr> text</strong> is read by an <a href=#input-adapters>input adapter</a>, tokenized by the lexer, and turned into <abbr title="Simple API for XML">SAX</abbr> events by the parser.</li> <li><strong>Binary formats</strong> (<abbr title="Binary JData">BJData</abbr>, <abbr title="Binary Object Notation 8">BON8</abbr>, <abbr title="Binary JSON">BSON</abbr>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>) are read by an input adapter and turned into the same <abbr title="Simple API for XML">SAX</abbr> events by the <code>binary_reader</code>.</li> <li>A <a href=#sax-interface><abbr title="Simple API for XML">SAX</abbr> consumer</a> receives the events. The one used by <a href=../../api/basic_json/parse/ ><code>parse</code></a> builds a <code>basic_json</code> value tree.</li> <li>The <code>serializer</code> (<abbr title="JavaScript Object Notation">JSON</abbr> text) or the <code>binary_writer</code> (binary formats) writes a value tree to an <a href=#output-adapters>output adapter</a>.</li> </ul> <h2 id=source-layout>Source layout<a class=headerlink href=#source-layout title="Permanent link">&para;</a></h2> <p>The public headers are in <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code></a>:</p> <ul> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json.hpp"><code>json.hpp</code></a> defines class <a href=../../api/basic_json/ ><code>basic_json</code></a>.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp"><code>json_fwd.hpp</code></a> contains forward declarations.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/adl_serializer.hpp"><code>adl_serializer.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/byte_container_with_subtype.hpp"><code>byte_container_with_subtype.hpp</code></a>, and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/ordered_map.hpp"><code>ordered_map.hpp</code></a> define <a href=../../api/adl_serializer/ ><code>adl_serializer</code></a>, <a href=../../api/byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a>, and <a href=../../api/ordered_map/ ><code>ordered_map</code></a>.</li> <li><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_view.hpp"><code>json_view.hpp</code></a> is a separate, optional header that defines <a href=../../api/basic_json_document/ ><code>basic_json_document</code></a> and <a href=../../api/basic_json_view/ ><code>basic_json_view</code></a>, a flat-index, read-only, non-owning way to look at a parsed <abbr title="JavaScript Object Notation">JSON</abbr> text; see <a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a>. It builds on <code>json.hpp</code> internals (it requires the same library version) and has its own <code>detail/view/</code> subdirectory.</li> </ul> <p>Everything else lives in <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann/detail"><code>detail/</code></a> and namespace <code>nlohmann::detail</code>, which is not part of the public <abbr title="Application Programming Interface">API</abbr>. Paths below are relative to <code>include/nlohmann</code>.</p> <table> <thead> <tr> <th>Component</th> <th>Location</th> </tr> </thead> <tbody> <tr> <td>Value type enumeration</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/value_t.hpp"><code>detail/value_t.hpp</code></a></td> </tr> <tr> <td>Input adapters</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/input_adapters.hpp"><code>detail/input/input_adapters.hpp</code></a></td> </tr> <tr> <td>Lexer</td> <td><a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/lexer.hpp"><code>detail/input/lexer.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/number_parse.hpp"><code>detail/input/number_parse.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/string_scan.hpp"><code>detail/input/string_scan.hpp</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/input/simd_scan.hpp"><code>detail/input/simd_scan.hpp</code></a></td> </tr> <tr> <td>Parser</tLine truncated
<span class=p>{</span>
<span class=w> </span><span class=c1>/// the type of the current element</span>
<span class=w> </span><span class=n>value_t</span><span class=w> </span><span class=n>m_type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>value_t</span><span class=o>::</span><span class=n>null</span><span class=p>;</span>
@@ -65,7 +65,7 @@
16-31: "extra"
32-63: "off"
64-95: "len"
96-127: "next"</code></pre> <table> <thead> <tr> <th>Bytes</th> <th>Field</th> <th>Type</th> <th>Contents</th> </tr> </thead> <tbody> <tr> <td>0</td> <td><code>kind</code></td> <td><code>uint8_t</code></td> <td>the type, numbered as <a href=../../api/basic_json/value_t/ ><code>value_t</code></a>: 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a <a href=../../api/basic_json_view/is_discarded/ >discarded</a> view has none</td> </tr> <tr> <td>1</td> <td><code>flags</code></td> <td><code>uint8_t</code></td> <td>bits 0-1: where a string's bytes (or a number's token) are (0: the source text, 1: the buffer of decoded strings, for strings with escapes, 2: the edit buffer); bit 2: the value of a boolean; bit 3: moved, bit 4: new, bit 5: linked (see below)</td> </tr> <tr> <td>2-3</td> <td><code>extra</code></td> <td><code>uint16_t</code></td> <td>numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0</td> </tr> <tr> <td>4-7</td> <td><code>off</code></td> <td><code>uint32_t</code></td> <td>where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object</td> </tr> <tr> <td>8-11</td> <td><code>len</code></td> <td><code>uint32_t</code></td> <td>strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements</td> </tr> <tr> <td>12-15</td> <td><code>next</code></td> <td><code>uint32_t</code></td> <td>arrays and objects: the number of nodes of the subtree, including the node itself</td> </tr> </tbody> </table> <ul> <li><strong>Integers</strong> keep their converted value in bytes 8-15 instead of <code>len</code> and <code>next</code>; the length of their token follows from the number of digits in <code>extra</code> (and the sign). Non-negative integers are unsigned integers, as with <a href=../../api/basic_json/parse/ ><code>parse</code></a>.</li> <li><strong>Floats</strong> keep only their token. The digit layout in <code>extra</code> lets the conversion read the digits without scanning the token again, and only when the value is read.</li> <li><strong>Object members</strong> are the node of the key (a string) followed by the nodes of the value.</li> <li><strong>Navigation</strong> needs no pointers: the elements of an array or object follow its node, and the node after a value's subtree is <code>next</code> nodes further for an array or object, and the next node otherwise (<code>document_data::after</code>). Views step from element to element this way and skip whole subtrees in constant time.</li> <li><strong>Offsets</strong> are 32 bits wide, so a document is limited to 4294967279 bytes, 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes (a margin below 2^32 for positions one scanner step past the end of the text; <code>out_of_range.416</code>).</li> <li><strong>Large objects</strong> (128 members or more) get a hash index for their keys after parsing (<a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp"><code>detail/view/object_index.hpp</code></a>): an open-addressing table whose slots hold the distance from the object's node to a key's node, so that a lookup does not compare every key. Of duplicate keys the table leads to the first, as a linear search does. The object's <code>extra</code> holds the number of its table. Only 65,535 tables fit into <code>extra</code>; objects beyond them are searched linearly.</li> </ul> <p>For example, <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> becomes five nodes. Each node's elements follow it, and <code>next</code> leads from an array or object past its subtree:</p> <pre class=mermaid><code>flowchart LR
96-127: "next"</code></pre> <p class=nj-caption>Layout of one 16-byte node of a <abbr title="JavaScript Object Notation">JSON</abbr> view index. Each row is 32 bits wide, and the numbers are the bit offsets of the fields <code>kind</code>, <code>flags</code>, <code>extra</code>, <code>off</code>, <code>len</code>, and <code>next</code>.</p> <table> <thead> <tr> <th>Bytes</th> <th>Field</th> <th>Type</th> <th>Contents</th> </tr> </thead> <tbody> <tr> <td>0</td> <td><code>kind</code></td> <td><code>uint8_t</code></td> <td>the type, numbered as <a href=../../api/basic_json/value_t/ ><code>value_t</code></a>: 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a <a href=../../api/basic_json_view/is_discarded/ >discarded</a> view has none</td> </tr> <tr> <td>1</td> <td><code>flags</code></td> <td><code>uint8_t</code></td> <td>bits 0-1: where a string's bytes (or a number's token) are (0: the source text, 1: the buffer of decoded strings, for strings with escapes, 2: the edit buffer); bit 2: the value of a boolean; bit 3: moved, bit 4: new, bit 5: linked (see below)</td> </tr> <tr> <td>2-3</td> <td><code>extra</code></td> <td><code>uint16_t</code></td> <td>numbers: the number of integer digits (low byte) and fraction digits (high byte), 255 for more; objects: the number of their key hash index (1-based), or 0; otherwise 0</td> </tr> <tr> <td>4-7</td> <td><code>off</code></td> <td><code>uint32_t</code></td> <td>where the value starts: the first byte after a string's opening quote (or its position in the buffer of decoded strings), the first byte of a number or literal, the bracket of an array or object</td> </tr> <tr> <td>8-11</td> <td><code>len</code></td> <td><code>uint32_t</code></td> <td>strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements</td> </tr> <tr> <td>12-15</td> <td><code>next</code></td> <td><code>uint32_t</code></td> <td>arrays and objects: the number of nodes of the subtree, including the node itself</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.</p> <ul> <li><strong>Integers</strong> keep their converted value in bytes 8-15 instead of <code>len</code> and <code>next</code>; the length of their token follows from the number of digits in <code>extra</code> (and the sign). Non-negative integers are unsigned integers, as with <a href=../../api/basic_json/parse/ ><code>parse</code></a>.</li> <li><strong>Floats</strong> keep only their token. The digit layout in <code>extra</code> lets the conversion read the digits without scanning the token again, and only when the value is read.</li> <li><strong>Object members</strong> are the node of the key (a string) followed by the nodes of the value.</li> <li><strong>Navigation</strong> needs no pointers: the elements of an array or object follow its node, and the node after a value's subtree is <code>next</code> nodes further for an array or object, and the next node otherwise (<code>document_data::after</code>). Views step from element to element this way and skip whole subtrees in constant time.</li> <li><strong>Offsets</strong> are 32 bits wide, so a document is limited to 4294967279 bytes, 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes (a margin below 2^32 for positions one scanner step past the end of the text; <code>out_of_range.416</code>).</li> <li><strong>Large objects</strong> (128 members or more) get a hash index for their keys after parsing (<a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/object_index.hpp"><code>detail/view/object_index.hpp</code></a>): an open-addressing table whose slots hold the distance from the object's node to a key's node, so that a lookup does not compare every key. Of duplicate keys the table leads to the first, as a linear search does. The object's <code>extra</code> holds the number of its table. Only 65,535 tables fit into <code>extra</code>; objects beyond them are searched linearly.</li> </ul> <p>For example, <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> becomes five nodes. Each node's elements follow it, and <code>next</code> leads from an array or object past its subtree:</p> <pre class=mermaid><code>flowchart LR
n0["0: object&lt;br&gt;len 1, next 5"]
n1["1: key a"]
n2["2: array&lt;br&gt;len 2, next 3"]
@@ -74,7 +74,7 @@
e(["end"])
n0 --&gt; n1 --&gt; n2 --&gt; n3 --&gt; n4 --&gt; e
n0 -. next .-&gt; e
n2 -. next .-&gt; e</code></pre> <table> <thead> <tr> <th>Node</th> <th><code>kind</code></th> <th><code>extra</code></th> <th><code>off</code></th> <th><code>len</code></th> <th><code>next</code></th> </tr> </thead> <tbody> <tr> <td>0</td> <td>1 (object)</td> <td>0</td> <td>0</td> <td>1</td> <td>5</td> </tr> <tr> <td>1</td> <td>3 (string)</td> <td>0</td> <td>2</td> <td>1</td> <td>0</td> </tr> <tr> <td>2</td> <td>2 (array)</td> <td>0</td> <td>6</td> <td>2</td> <td>3</td> </tr> <tr> <td>3</td> <td>6 (unsigned integer)</td> <td>0x0001</td> <td>7</td> <td>-</td> <td>-</td> </tr> <tr> <td>4</td> <td>7 (float)</td> <td>0x0101</td> <td>10</td> <td>3</td> <td>0</td> </tr> </tbody> </table> <p>All <code>flags</code> are 0. The integer's bytes 8-15 hold its value, 1; its <code>extra</code> says it has one digit. The float's <code>extra</code> says it has one integer and one fraction digit, and its <code>len</code> is that of the token <code>2.5</code>.</p> <p>Editable documents (<a href=../../api/json_editable_document/ ><code>json_editable_document</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit.hpp"><code>detail/view/edit.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit_storage.hpp"><code>detail/view/edit_storage.hpp</code></a>) never write the source text and never move or resize the parsed index, so views stay valid while the document is edited:</p> <ul> <li>A new scalar is written over its node. Its text (a string, or the token of a number as <code>dump()</code> writes it) goes to the edit buffer, which <code>flags</code> bits 0-1 then name.</li> <li>An array or object whose elements change gets the flag <em>moved</em> (bit 3): its elements then live in a separate sequence (a header node, then the entries), whose number is in <code>off</code>. The entries are links (<code>kind</code> 10), whose bytes 8-15 hold the address of the value's node, so values never move.</li> <li>A node written by an edit gets the flag <em>new</em> (bit 4): it has no position in the source text.</li> <li>A value that an entry of such a sequence links to gets the flag <em>linked</em> (bit 5): its extent in the parsed layout (<code>next</code>) no longer matters, so a scalar can replace an array or object there in place.</li> <li>Views of read-only documents compile without any of this: how views walk the index is a template parameter (<code>navigation&lt;Editable&gt;</code>).</li> </ul> <p>Images (<a href=../../api/basic_json_document/save/ ><code>save</code></a> and <a href=../../api/basic_json_document/load/ ><code>load</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp"><code>detail/view/image.hpp</code></a>) store the nodes as they are: a 64-byte header (the magic bytes <code>NJVI</code>, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since <code>load</code> rebuilds the indexes. So a change of the node layout is a change of the image format: it must raise <code>image_version</code>, and <code>load</code> then rejects images of other versions (<code>parse_error.116</code>) instead of misreading them.</p> <h2 id=input-adapters>Input adapters<a class=headerlink href=#input-adapters title="Permanent link">&para;</a></h2> <p>Input is read via <strong>input adapters</strong> that abstract a source. Every input adapter provides this interface:</p> <div class=highlight><pre><span></span><code><span class=c1>/// the type of the characters in the input</span>
n2 -. next .-&gt; e</code></pre> <p class=nj-caption>The five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code> in document order. Solid arrows lead from each node to the one after it; dotted arrows show where <code>next</code> leads from the object and the array, past their subtrees.</p> <table> <thead> <tr> <th>Node</th> <th><code>kind</code></th> <th><code>extra</code></th> <th><code>off</code></th> <th><code>len</code></th> <th><code>next</code></th> </tr> </thead> <tbody> <tr> <td>0</td> <td>1 (object)</td> <td>0</td> <td>0</td> <td>1</td> <td>5</td> </tr> <tr> <td>1</td> <td>3 (string)</td> <td>0</td> <td>2</td> <td>1</td> <td>0</td> </tr> <tr> <td>2</td> <td>2 (array)</td> <td>0</td> <td>6</td> <td>2</td> <td>3</td> </tr> <tr> <td>3</td> <td>6 (unsigned integer)</td> <td>0x0001</td> <td>7</td> <td>-</td> <td>-</td> </tr> <tr> <td>4</td> <td>7 (float)</td> <td>0x0101</td> <td>10</td> <td>3</td> <td>0</td> </tr> </tbody> </table> <p class=nj-table-caption>Fields of the five nodes of <code class=highlight><span class=p>{</span><span class=nt>"a"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mf>2.5</span><span class=p>]}</span></code>. <code>off</code> is the byte offset in the text, and - marks the bytes 8-15 that hold the integer's value instead of <code>len</code> and <code>next</code>.</p> <p>All <code>flags</code> are 0. The integer's bytes 8-15 hold its value, 1; its <code>extra</code> says it has one digit. The float's <code>extra</code> says it has one integer and one fraction digit, and its <code>len</code> is that of the token <code>2.5</code>.</p> <p>Editable documents (<a href=../../api/json_editable_document/ ><code>json_editable_document</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit.hpp"><code>detail/view/edit.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit_storage.hpp"><code>detail/view/edit_storage.hpp</code></a>) never write the source text and never move or resize the parsed index, so views stay valid while the document is edited:</p> <ul> <li>A new scalar is written over its node. Its text (a string, or the token of a number as <code>dump()</code> writes it) goes to the edit buffer, which <code>flags</code> bits 0-1 then name.</li> <li>An array or object whose elements change gets the flag <em>moved</em> (bit 3): its elements then live in a separate sequence (a header node, then the entries), whose number is in <code>off</code>. The entries are links (<code>kind</code> 10), whose bytes 8-15 hold the address of the value's node, so values never move.</li> <li>A node written by an edit gets the flag <em>new</em> (bit 4): it has no position in the source text.</li> <li>A value that an entry of such a sequence links to gets the flag <em>linked</em> (bit 5): its extent in the parsed layout (<code>next</code>) no longer matters, so a scalar can replace an array or object there in place.</li> <li>Views of read-only documents compile without any of this: how views walk the index is a template parameter (<code>navigation&lt;Editable&gt;</code>).</li> </ul> <p>Images (<a href=../../api/basic_json_document/save/ ><code>save</code></a> and <a href=../../api/basic_json_document/load/ ><code>load</code></a>, <a href="https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/image.hpp"><code>detail/view/image.hpp</code></a>) store the nodes as they are: a 64-byte header (the magic bytes <code>NJVI</code>, a format version, the sizes, and reserved bytes that must be zero), the nodes, the text, and the decoded strings. An edited document is first written in document order, as the parser would have written it (without links), and the numbers of the hash indexes are cleared, since <code>load</code> rebuilds the indexes. So a change of the node layout is a change of the image format: it must raise <code>image_version</code>, and <code>load</code> then rejects images of other versions (<code>parse_error.116</code>) instead of misreading them.</p> <h2 id=input-adapters>Input adapters<a class=headerlink href=#input-adapters title="Permanent link">&para;</a></h2> <p>Input is read via <strong>input adapters</strong> that abstract a source. Every input adapter provides this interface:</p> <div class=highlight><pre><span></span><code><span class=c1>/// the type of the characters in the input</span>
<span class=k>using</span><span class=w> </span><span class=n>char_type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>...;</span>
<span class=c1>/// read a single character; returns std::char_traits&lt;char_type&gt;::eof() at the end of the input</span>
@@ -84,12 +84,58 @@
<span class=c1>/// (used by the binary readers)</span>
<span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=o>&gt;</span>
<span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=n>get_elements</span><span class=p>(</span><span class=n>T</span><span class=o>*</span><span class=w> </span><span class=n>dest</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=n>count</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mi>1</span><span class=p>);</span>
</code></pre></div> <p>The lexer detects two optional extensions at compile time. Only <code>iterator_input_adapter</code> provides them, and only for random-access input of single-byte characters:</p> <ul> <li><code>supports_seek</code>, <code>get_consumed_count()</code>, and <code>copy_consumed_range()</code> let the lexer reconstruct already consumed input for error messages instead of copying every character it reads. With <code>get_read_count()</code> and <code>count_consumed_lines()</code>, the lexer also derives the read position from the adapter and counts lines only when an error needs them, instead of counting characters and lines on every read.</li> <li><code>supports_bulk_scan</code>, <code>bulk_data()</code>, <code>bulk_remaining()</code>, and <code>bulk_skip()</code> let the lexer scan strings directly in contiguous memory, several bytes at a time, and skip the spaces that indent a line in 8-byte steps.</li> </ul> <p>The function <code>input_adapter</code> picks the right adapter for the argument passed to <code>parse</code>, <code>accept</code>, <code>sax_parse</code>, or the <code>from_*</code> functions:</p> <ul> <li><code>iterator_input_adapter</code> reads from an iterator range, which also covers strings, containers, and pointers.</li> <li><code>wide_string_input_adapter</code> reads from ranges of <code>wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code> and converts them to <abbr title="Unicode Transformation Format">UTF</abbr>-8. It cannot be used for binary formats; its <code>get_elements()</code> throws.</li> <li><code>input_stream_adapter</code> reads from a <code>std::istream</code>.</li> <li><code>file_input_adapter</code> reads from a <code>std::FILE*</code>.</li> </ul> <h2 id=sax-interface><abbr title="Simple API for XML">SAX</abbr> interface<a class=headerlink href=#sax-interface title="Permanent link">&para;</a></h2> <p>The parser does not build values itself. It reports what it reads as events to a <a href=../../features/parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr></a> consumer, which implements the interface <a href=../../api/json_sax/ ><code>json_sax</code></a>: <code>null</code>, <code>boolean</code>, <code>number_integer</code>, <code>number_unsigned</code>, <code>number_float</code>, <code>string</code>, <code>binary</code>, <code>start_object</code>, <code>key</code>, <code>end_object</code>, <code>start_array</code>, <code>end_array</code>, and <code>parse_error</code>.</p> <p>The library comes with two consumers in <code>detail/input/json_sax.hpp</code>:</p> <ul> <li><code>json_sax_dom_parser</code> builds a <a href=../../api/basic_json/ ><code>basic_json</code></a> value tree. <a href=../../api/basic_json/parse/ ><code>parse</code></a> uses it.</li> <li><code>json_sax_dom_callback_parser</code> does the same, but calls a <a href=../../features/parsing/parser_callbacks/ >parser callback</a> for each event, which can skip values. <code>parse</code> uses it when a callback is given.</li> </ul> <p>The <code>binary_reader</code> emits the same events for binary formats, so <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> works with a user-defined consumer for <abbr title="JavaScript Object Notation">JSON</abbr> and for all binary formats alike.</p> <h2 id=output-adapters>Output adapters<a class=headerlink href=#output-adapters title="Permanent link">&para;</a></h2> <p>Output is written via <strong>output adapters</strong>:</p> <div class=highlight><pre><span></span><code><span class=kt>void</span><span class=w> </span><span class=nf>write_character</span><span class=p>(</span><span class=n>CharType</span><span class=w> </span><span class=n>c</span><span class=p>);</span>
</code></pre></div> <p>The lexer detects two optional extensions at compile time. <code>iterator_input_adapter</code> provides both, and only for random-access input of single-byte characters. <code>input_stream_adapter</code> provides the second one (as a window onto the streambuf's buffer) unless <code>JSON_DISABLE_STREAM_BULK_SCAN</code> is defined:</p> <ul> <li><code>supports_seek</code>, <code>get_consumed_count()</code>, and <code>copy_consumed_range()</code> let the lexer reconstruct already consumed input for error messages instead of copying every character it reads. With <code>get_read_count()</code> and <code>count_consumed_lines()</code>, the lexer also derives the read position from the adapter and counts lines only when an error needs them, instead of counting characters and lines on every read.</li> <li><code>supports_bulk_scan</code>, <code>bulk_data()</code>, <code>bulk_remaining()</code>, and <code>bulk_skip()</code> let the lexer scan strings directly in contiguous memory, several bytes at a time, and skip the spaces that indent a line in 8-byte steps.</li> </ul> <p>The function <code>input_adapter</code> picks the right adapter for the argument passed to <code>parse</code>, <code>accept</code>, <code>sax_parse</code>, or the <code>from_*</code> functions:</p> <ul> <li><code>iterator_input_adapter</code> reads from an iterator range, which also covers strings, containers, and pointers.</li> <li><code>wide_string_input_adapter</code> reads from ranges of <code>wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code> and converts them to <abbr title="Unicode Transformation Format">UTF</abbr>-8. It cannot be used for binary formats; its <code>get_elements()</code> throws.</li> <li><code>input_stream_adapter</code> reads from a <code>std::istream</code>.</li> <li><code>file_input_adapter</code> reads from a <code>std::FILE*</code>.</li> </ul> <p>The adapters have no common base class: the lexer and the parser are templates on the adapter type, and <code>wide_string_input_adapter</code> wraps an <code>iterator_input_adapter</code>:</p> <pre class=mermaid><code>classDiagram
class input_adapter ["input adapter"] {
&lt;&lt;concept&gt;&gt;
+char_type
+get_character() int_type
+get_elements(T* dest, size_t count) size_t
}
class iterator_input_adapter {
-IteratorType current
-SentinelType end
}
class wide_string_input_adapter {
-BaseInputAdapter base_adapter
}
class input_stream_adapter {
-std::istream* is
-std::streambuf* sb
}
class file_input_adapter {
-std::FILE* m_file
}
input_adapter &lt;|.. iterator_input_adapter
input_adapter &lt;|.. wide_string_input_adapter
input_adapter &lt;|.. input_stream_adapter
input_adapter &lt;|.. file_input_adapter
wide_string_input_adapter o-- iterator_input_adapter : converts to UTF-8</code></pre> <p class=nj-caption>The input adapters as a class diagram. The dotted arrows mean that each adapter implements the input adapter concept; the diamond shows that <code>wide_string_input_adapter</code> holds an <code>iterator_input_adapter</code>.</p> <h2 id=sax-interface><abbr title="Simple API for XML">SAX</abbr> interface<a class=headerlink href=#sax-interface title="Permanent link">&para;</a></h2> <p>The parser does not build values itself. It reports what it reads as events to a <a href=../../features/parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr></a> consumer, which implements the interface <a href=../../api/json_sax/ ><code>json_sax</code></a>: <code>null</code>, <code>boolean</code>, <code>number_integer</code>, <code>number_unsigned</code>, <code>number_float</code>, <code>string</code>, <code>binary</code>, <code>start_object</code>, <code>key</code>, <code>end_object</code>, <code>start_array</code>, <code>end_array</code>, and <code>parse_error</code>.</p> <p>The library comes with two consumers in <code>detail/input/json_sax.hpp</code>:</p> <ul> <li><code>json_sax_dom_parser</code> builds a <a href=../../api/basic_json/ ><code>basic_json</code></a> value tree. <a href=../../api/basic_json/parse/ ><code>parse</code></a> uses it.</li> <li><code>json_sax_dom_callback_parser</code> does the same, but calls a <a href=../../features/parsing/parser_callbacks/ >parser callback</a> for each event, which can skip values. <code>parse</code> uses it when a callback is given.</li> </ul> <p>The <code>binary_reader</code> emits the same events for binary formats, so <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> works with a user-defined consumer for <abbr title="JavaScript Object Notation">JSON</abbr> and for all binary formats alike. The <a href=../../features/parsing/sax_interface/#sax-event-stepper><abbr title="Simple API for XML">SAX</abbr> event stepper</a> shows the events for a small input.</p> <h2 id=output-adapters>Output adapters<a class=headerlink href=#output-adapters title="Permanent link">&para;</a></h2> <p>Output is written via <strong>output adapters</strong>:</p> <div class=highlight><pre><span></span><code><span class=kt>void</span><span class=w> </span><span class=nf>write_character</span><span class=p>(</span><span class=n>CharType</span><span class=w> </span><span class=n>c</span><span class=p>);</span>
<span class=kt>void</span><span class=w> </span><span class=nf>write_characters</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>CharType</span><span class=o>*</span><span class=w> </span><span class=n>s</span><span class=p>,</span><span class=w> </span><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span><span class=w> </span><span class=n>length</span><span class=p>);</span>
</code></pre></div> <p>The <code>serializer</code> (used by <a href=../../api/basic_json/dump/ ><code>dump</code></a> and <a href=../../api/operator_ltlt/ ><code>operator&lt;&lt;</code></a>) and the <code>binary_writer</code> (used by the <code>to_*</code> functions) write to one of these adapters:</p> <ul> <li><code>output_vector_adapter</code> appends to a <code>std::vector</code>.</li> <li><code>output_stream_adapter</code> writes to a <code>std::ostream</code>.</li> <li><code>output_string_adapter</code> appends to a string.</li> </ul> <p>The <code>binary_writer</code> does not call an adapter for every byte. The <code>to_*</code> functions that return a <code>std::vector</code> write into the vector through a sink (<code>output_vector_sink</code>) that is not virtual. The functions that take an output adapter write through a sink (<code>output_adapter_sink</code>) that collects the output in a buffer of one kibibyte and passes it to the adapter in blocks, so that the adapter is called (and a stream locked) once per block instead of once per value.</p> <h2 id=value-conversion>Value conversion<a class=headerlink href=#value-conversion title="Permanent link">&para;</a></h2> <p>Values are converted from and to other types with the <code>JSONSerializer</code> template parameter. The default, <a href=../../api/adl_serializer/ ><code>adl_serializer</code></a>, calls the free functions</p> <div class=highlight><pre><span></span><code><span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=o>&gt;</span>
</code></pre></div> <p>The <code>serializer</code> (used by <a href=../../api/basic_json/dump/ ><code>dump</code></a> and <a href=../../api/operator_ltlt/ ><code>operator&lt;&lt;</code></a>) and the <code>binary_writer</code> (used by the <code>to_*</code> functions) write to one of these adapters:</p> <ul> <li><code>output_vector_adapter</code> appends to a <code>std::vector</code>.</li> <li><code>output_stream_adapter</code> writes to a <code>std::ostream</code>.</li> <li><code>output_string_adapter</code> appends to a string.</li> </ul> <p>They implement the abstract class <code>output_adapter_protocol</code>. The class <code>output_adapter</code> creates the one that matches its argument and holds it in a <code>std::shared_ptr</code> (<code>output_adapter_t</code>):</p> <pre class=mermaid><code>classDiagram
class output_adapter_protocol~CharType~ {
&lt;&lt;interface&gt;&gt;
+write_character(CharType c)*
+write_characters(const CharType* s, size_t length)*
}
class output_vector_adapter {
-std::vector&amp; v
}
class output_stream_adapter {
-std::basic_ostream&amp; stream
}
class output_string_adapter {
-StringType&amp; str
}
class output_adapter {
-output_adapter_t oa
}
output_adapter_protocol &lt;|-- output_vector_adapter
output_adapter_protocol &lt;|-- output_stream_adapter
output_adapter_protocol &lt;|-- output_string_adapter
output_adapter o-- output_adapter_protocol : shared_ptr</code></pre> <p class=nj-caption>The output adapters as a class diagram. The three adapters derive from <code>output_adapter_protocol</code> (solid arrows), and <code>output_adapter</code> holds one of them through a <code>shared_ptr</code> (diamond).</p> <p>The <code>binary_writer</code> does not call an adapter for every byte. The <code>to_*</code> functions that return a <code>std::vector</code> write into the vector through a sink (<code>output_vector_sink</code>) that is not virtual. The functions that take an output adapter write through a sink (<code>output_adapter_sink</code>) that collects the output in a buffer of one kibibyte and passes it to the adapter in blocks, so that the adapter is called (and a stream locked) once per block instead of once per value.</p> <h2 id=value-conversion>Value conversion<a class=headerlink href=#value-conversion title="Permanent link">&para;</a></h2> <p>Values are converted from and to other types with the <code>JSONSerializer</code> template parameter. The default, <a href=../../api/adl_serializer/ ><code>adl_serializer</code></a>, calls the free functions</p> <div class=highlight><pre><span></span><code><span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=o>&gt;</span>
<span class=kt>void</span><span class=w> </span><span class=n>to_json</span><span class=p>(</span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=k>const</span><span class=w> </span><span class=n>T</span><span class=o>&amp;</span><span class=w> </span><span class=n>t</span><span class=p>);</span>
<span class=k>template</span><span class=o>&lt;</span><span class=k>class</span><span class=w> </span><span class=nc>T</span><span class=o>&gt;</span>
<span class=kt>void</span><span class=w> </span><span class=n>from_json</span><span class=p>(</span><span class=k>const</span><span class=w> </span><span class=n>basic_json</span><span class=o>&amp;</span><span class=w> </span><span class=n>j</span><span class=p>,</span><span class=w> </span><span class=n>T</span><span class=o>&amp;</span><span class=w> </span><span class=n>t</span><span class=p>);</span>
</code></pre></div> <p>found by argument-dependent lookup. The library defines them for standard types in <code>detail/conversions</code>; users add them for their own types, see <a href=../../features/arbitrary_types/ >Arbitrary Type Conversions</a>. The <a href=../../features/macros/ >serialization macros</a> generate these functions.</p> <h2 id=additional-features>Additional features<a class=headerlink href=#additional-features title="Permanent link">&para;</a></h2> <ul> <li><a href=../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> (class <code>json_pointer</code>) addresses values inside a tree. It is also the basis of <a href=../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a>.</li> <li><a href=../../features/binary_formats/ >Binary formats</a> are read by <code>binary_reader</code> and written by <code>binary_writer</code>.</li> <li>A <a href=../../api/basic_json/json_base_class_t/ >custom base class</a> can add members to every <a href=../../api/basic_json/ ><code>basic_json</code></a> value.</li> <li><a href=../../features/macros/ >Serialization macros</a> generate <code>to_json</code> and <code>from_json</code> functions for user-defined types.</li> </ul> <h2 id=details-namespace>Details namespace<a class=headerlink href=#details-namespace title="Permanent link">&para;</a></h2> <p>Namespace <code>nlohmann::detail</code> contains all implementation details. It is not part of the public <abbr title="Application Programming Interface">API</abbr> and may change in any release. Besides the components above, it contains:</p> <ul> <li>type traits to detect the capabilities of user-defined types (<code>detail/meta/type_traits.hpp</code>),</li> <li>backports of C++14/17 features to C++11 (<code>detail/meta/cpp_future.hpp</code>), and</li> <li>helpers such as <code>string_concat</code> and <code>string_escape</code>.</li> </ul> <!-- 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 23, 2026 04:52:58 UTC">October 23, 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 5Line truncated
</code></pre></div> <p>found by argument-dependent lookup. The library defines them for standard types in <code>detail/conversions</code>; users add them for their own types, see <a href=../../features/arbitrary_types/ >Arbitrary Type Conversions</a>. The <a href=../../features/macros/ >serialization macros</a> generate these functions.</p> <h2 id=additional-features>Additional features<a class=headerlink href=#additional-features title="Permanent link">&para;</a></h2> <ul> <li><a href=../../features/json_pointer/ ><abbr title="JavaScript Object Notation">JSON</abbr> Pointer</a> (class <code>json_pointer</code>) addresses values inside a tree. It is also the basis of <a href=../../features/json_patch/ ><abbr title="JavaScript Object Notation">JSON</abbr> Patch</a>.</li> <li><a href=../../features/binary_formats/ >Binary formats</a> are read by <code>binary_reader</code> and written by <code>binary_writer</code>.</li> <li>A <a href=../../api/basic_json/json_base_class_t/ >custom base class</a> can add members to every <a href=../../api/basic_json/ ><code>basic_json</code></a> value.</li> <li><a href=../../features/macros/ >Serialization macros</a> generate <code>to_json</code> and <code>from_json</code> functions for user-defined types.</li> </ul> <h2 id=details-namespace>Details namespace<a class=headerlink href=#details-namespace title="Permanent link">&para;</a></h2> <p>Namespace <code>nlohmann::detail</code> contains all implementation details. It is not part of the public <abbr title="Application Programming Interface">API</abbr> and may change in any release. Besides the components above, it contains:</p> <ul> <li>type traits to detect the capabilities of user-defined types (<code>detail/meta/type_traits.hpp</code>),</li> <li>backports of C++14/17 features to C++11 (<code>detail/meta/cpp_future.hpp</code>), and</li> <li>helpers such as <code>string_concat</code> and <code>string_escape</code>.</li> </ul> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/ ><code>basic_json</code></a> - the main class and all its member functions</li> <li><a href=../../api/adl_serializer/ ><code>adl_serializer</code></a> - customization point for type conversions</li> <li><a href=../../api/json_sax/ ><code>json_sax</code></a> - interface of the <abbr title="Simple API for XML">SAX</abbr> parser events</li> <li><a href=../../features/parsing/sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> Interface</a> - how to consume parser events without building a <abbr title="Document Object Model">DOM</abbr></li> <li><a href=../../features/json_view/ >Zero-copy <abbr title="JavaScript Object Notation">JSON</abbr> views</a> - the flat node index that backs views and documents</li> <li><a href=../../features/types/template_parameters/ >Template Parameter Requirements</a> - the template parameters of basic_json</li> <li><a href=../../features/serialization/ >Serialization</a> - the output side of the library</li> <li><a href=../../features/namespace/ ><code>nlohmann</code> Namespace</a> - how the library namespace is structured</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../design_goals/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Design goals"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 Line truncated
+85 -2
View File
@@ -29,6 +29,8 @@ flowchart LR
oa --> output
```
Data flow through the library: input runs left to right through an input adapter and the lexer and parser (JSON text) or the `binary_reader` (binary formats) into SAX events, which build the value tree; the `serializer` or the `binary_writer` writes the tree to an output adapter.
- **JSON text** is read by an [input adapter](#input-adapters), tokenized by the lexer, and turned into SAX events by the parser.
- **Binary formats** (BJData, BON8, BSON, CBOR, MessagePack, UBJSON) are read by an input adapter and turned into the same SAX events by the `binary_reader`.
- A [SAX consumer](#sax-interface) receives the events. The one used by [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) builds a `basic_json` value tree.
@@ -160,6 +162,8 @@ packet-beta
96-127: "next"
```
Layout of one 16-byte node of a JSON view index. Each row is 32 bits wide, and the numbers are the bit offsets of the fields `kind`, `flags`, `extra`, `off`, `len`, and `next`.
| Bytes | Field | Type | Contents |
| ----- | ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `kind` | `uint8_t` | the type, numbered as [`value_t`](https://json.nlohmann.me/api/basic_json/value_t/index.md): 0 null, 1 object, 2 array, 3 string, 4 boolean, 5 signed integer, 6 unsigned integer, 7 float; 10 for a link (see below). There is no node for a discarded value: a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view has none |
@@ -169,6 +173,8 @@ packet-beta
| 8-11 | `len` | `uint32_t` | strings: the length after decoding; floats and literals: the length of the token; arrays and objects: the number of elements |
| 12-15 | `next` | `uint32_t` | arrays and objects: the number of nodes of the subtree, including the node itself |
Fields of a node, by their byte offset within the 16-byte node. Integers use bytes 8-15 differently, see below.
- **Integers** keep their converted value in bytes 8-15 instead of `len` and `next`; the length of their token follows from the number of digits in `extra` (and the sign). Non-negative integers are unsigned integers, as with [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md).
- **Floats** keep only their token. The digit layout in `extra` lets the conversion read the digits without scanning the token again, and only when the value is read.
- **Object members** are the node of the key (a string) followed by the nodes of the value.
@@ -191,6 +197,8 @@ flowchart LR
n2 -. next .-> e
```
The five nodes of `{"a": [1, 2.5]}` in document order. Solid arrows lead from each node to the one after it; dotted arrows show where `next` leads from the object and the array, past their subtrees.
| Node | `kind` | `extra` | `off` | `len` | `next` |
| ---- | -------------------- | ------- | ----- | ----- | ------ |
| 0 | 1 (object) | 0 | 0 | 1 | 5 |
@@ -199,6 +207,8 @@ flowchart LR
| 3 | 6 (unsigned integer) | 0x0001 | 7 | - | - |
| 4 | 7 (float) | 0x0101 | 10 | 3 | 0 |
Fields of the five nodes of `{"a": [1, 2.5]}`. `off` is the byte offset in the text, and - marks the bytes 8-15 that hold the integer's value instead of `len` and `next`.
All `flags` are 0. The integer's bytes 8-15 hold its value, 1; its `extra` says it has one digit. The float's `extra` says it has one integer and one fraction digit, and its `len` is that of the token `2.5`.
Editable documents ([`json_editable_document`](https://json.nlohmann.me/api/json_editable_document/index.md), [`detail/view/edit.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit.hpp) and [`detail/view/edit_storage.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/detail/view/edit_storage.hpp)) never write the source text and never move or resize the parsed index, so views stay valid while the document is edited:
@@ -228,7 +238,7 @@ template<class T>
std::size_t get_elements(T* dest, std::size_t count = 1);
```
The lexer detects two optional extensions at compile time. Only `iterator_input_adapter` provides them, and only for random-access input of single-byte characters:
The lexer detects two optional extensions at compile time. `iterator_input_adapter` provides both, and only for random-access input of single-byte characters. `input_stream_adapter` provides the second one (as a window onto the streambuf's buffer) unless `JSON_DISABLE_STREAM_BULK_SCAN` is defined:
- `supports_seek`, `get_consumed_count()`, and `copy_consumed_range()` let the lexer reconstruct already consumed input for error messages instead of copying every character it reads. With `get_read_count()` and `count_consumed_lines()`, the lexer also derives the read position from the adapter and counts lines only when an error needs them, instead of counting characters and lines on every read.
- `supports_bulk_scan`, `bulk_data()`, `bulk_remaining()`, and `bulk_skip()` let the lexer scan strings directly in contiguous memory, several bytes at a time, and skip the spaces that indent a line in 8-byte steps.
@@ -240,6 +250,39 @@ The function `input_adapter` picks the right adapter for the argument passed to
- `input_stream_adapter` reads from a `std::istream`.
- `file_input_adapter` reads from a `std::FILE*`.
The adapters have no common base class: the lexer and the parser are templates on the adapter type, and `wide_string_input_adapter` wraps an `iterator_input_adapter`:
```
classDiagram
class input_adapter ["input adapter"] {
<<concept>>
+char_type
+get_character() int_type
+get_elements(T* dest, size_t count) size_t
}
class iterator_input_adapter {
-IteratorType current
-SentinelType end
}
class wide_string_input_adapter {
-BaseInputAdapter base_adapter
}
class input_stream_adapter {
-std::istream* is
-std::streambuf* sb
}
class file_input_adapter {
-std::FILE* m_file
}
input_adapter <|.. iterator_input_adapter
input_adapter <|.. wide_string_input_adapter
input_adapter <|.. input_stream_adapter
input_adapter <|.. file_input_adapter
wide_string_input_adapter o-- iterator_input_adapter : converts to UTF-8
```
The input adapters as a class diagram. The dotted arrows mean that each adapter implements the input adapter concept; the diamond shows that `wide_string_input_adapter` holds an `iterator_input_adapter`.
## SAX interface
The parser does not build values itself. It reports what it reads as events to a [SAX](https://json.nlohmann.me/features/parsing/sax_interface/index.md) consumer, which implements the interface [`json_sax`](https://json.nlohmann.me/api/json_sax/index.md): `null`, `boolean`, `number_integer`, `number_unsigned`, `number_float`, `string`, `binary`, `start_object`, `key`, `end_object`, `start_array`, `end_array`, and `parse_error`.
@@ -249,7 +292,7 @@ The library comes with two consumers in `detail/input/json_sax.hpp`:
- `json_sax_dom_parser` builds a [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) value tree. [`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md) uses it.
- `json_sax_dom_callback_parser` does the same, but calls a [parser callback](https://json.nlohmann.me/features/parsing/parser_callbacks/index.md) for each event, which can skip values. `parse` uses it when a callback is given.
The `binary_reader` emits the same events for binary formats, so [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) works with a user-defined consumer for JSON and for all binary formats alike.
The `binary_reader` emits the same events for binary formats, so [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) works with a user-defined consumer for JSON and for all binary formats alike. The [SAX event stepper](https://json.nlohmann.me/features/parsing/sax_interface/#sax-event-stepper) shows the events for a small input.
## Output adapters
@@ -267,6 +310,35 @@ The `serializer` (used by [`dump`](https://json.nlohmann.me/api/basic_json/dump/
- `output_stream_adapter` writes to a `std::ostream`.
- `output_string_adapter` appends to a string.
They implement the abstract class `output_adapter_protocol`. The class `output_adapter` creates the one that matches its argument and holds it in a `std::shared_ptr` (`output_adapter_t`):
```
classDiagram
class output_adapter_protocol~CharType~ {
<<interface>>
+write_character(CharType c)*
+write_characters(const CharType* s, size_t length)*
}
class output_vector_adapter {
-std::vector& v
}
class output_stream_adapter {
-std::basic_ostream& stream
}
class output_string_adapter {
-StringType& str
}
class output_adapter {
-output_adapter_t oa
}
output_adapter_protocol <|-- output_vector_adapter
output_adapter_protocol <|-- output_stream_adapter
output_adapter_protocol <|-- output_string_adapter
output_adapter o-- output_adapter_protocol : shared_ptr
```
The output adapters as a class diagram. The three adapters derive from `output_adapter_protocol` (solid arrows), and `output_adapter` holds one of them through a `shared_ptr` (diamond).
The `binary_writer` does not call an adapter for every byte. The `to_*` functions that return a `std::vector` write into the vector through a sink (`output_vector_sink`) that is not virtual. The functions that take an output adapter write through a sink (`output_adapter_sink`) that collects the output in a buffer of one kibibyte and passes it to the adapter in blocks, so that the adapter is called (and a stream locked) once per block instead of once per value.
## Value conversion
@@ -297,3 +369,14 @@ Namespace `nlohmann::detail` contains all implementation details. It is not part
- type traits to detect the capabilities of user-defined types (`detail/meta/type_traits.hpp`),
- backports of C++14/17 features to C++11 (`detail/meta/cpp_future.hpp`), and
- helpers such as `string_concat` and `string_escape`.
## See also
- [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) - the main class and all its member functions
- [`adl_serializer`](https://json.nlohmann.me/api/adl_serializer/index.md) - customization point for type conversions
- [`json_sax`](https://json.nlohmann.me/api/json_sax/index.md) - interface of the SAX parser events
- [SAX Interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) - how to consume parser events without building a DOM
- [Zero-copy JSON views](https://json.nlohmann.me/features/json_view/index.md) - the flat node index that backs views and documents
- [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/index.md) - the template parameters of basic_json
- [Serialization](https://json.nlohmann.me/features/serialization/index.md) - the output side of the library
- [`nlohmann` Namespace](https://json.nlohmann.me/features/namespace/index.md) - how the library namespace is structured