deploy: ca91678af1

features/parsing/index.html

@@ -4,4 +4,4 @@
 <span class=c1>// parse from a file</span>
 <span class=n>std</span><span class=o>::</span><span class=n>ifstream</span><span class=w> </span><span class=n>f</span><span class=p>(</span><span class=s>&quot;example.json&quot;</span><span class=p>);</span>
 <span class=n>json</span><span class=w> </span><span class=n>data</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</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
-</code></pre></div> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <h2 id=sax-vs-dom-parsing><abbr title="Simple API for XML">SAX</abbr> vs. <abbr title="Document Object Model">DOM</abbr> parsing<a class=headerlink href=#sax-vs-dom-parsing title="Permanent link">&para;</a></h2> <p>The library offers two parsing models:</p> <ul> <li><strong><abbr title="Document Object Model">DOM</abbr> parsing</strong> (the default): the complete input is read and stored as an in-memory <code>basic_json</code> value that can be traversed and modified freely. This is what <a href=../../api/basic_json/parse/ ><code>parse</code></a> does, and it is the right choice for most use cases.</li> <li><strong><abbr title="Simple API for XML">SAX</abbr> parsing</strong>: instead of building a value, the parser reports events (such as "a string was read" or "an object started") to a handler that you implement. This avoids building the full value in memory and is useful for very large inputs or when you only need to extract parts of the input. See the <a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> for details and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> for the <abbr title="Application Programming Interfaces">API</abbr>.</li> </ul> <p>You can influence a <abbr title="Document Object Model">DOM</abbr> parse without switching to the <abbr title="Simple API for XML">SAX</abbr> interface by passing a <a href=parser_callbacks/ >parser callback</a>, which is called during parsing and can, for example, discard parts of the input.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <p>When the input is not valid <abbr title="JavaScript Object Notation">JSON</abbr>, the <code>parse</code> function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or <a href=../../api/basic_json/accept/ ><code>accept</code></a> can be used to only check whether an input is valid <abbr title="JavaScript Object Notation">JSON</abbr>. See <a href=parse_exceptions/ >parsing and exceptions</a> for the available options.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json/accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> - parse newline-delimited <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=parser_callbacks/ >parser callbacks</a> - influence the parsing by a callback function</li> <li><a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - implement a custom <abbr title="Simple API for XML">SAX</abbr> handler</li> <li><a href=parse_exceptions/ >parsing and exceptions</a> - control error handling</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="July 9, 2026 04:44:51 UTC">July 9, 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.sliceLine truncated
+</code></pre></div> <p>The input must be encoded in <abbr title="Unicode Transformation Format">UTF</abbr>-8; other encodings are not supported. A single input may contain only one <abbr title="JavaScript Object Notation">JSON</abbr> value. Inputs consisting of multiple values separated by newlines are handled by the <a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> format.</p> <p>By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the <code>parse</code> function — see <a href=../comments/ >comments</a> and <a href=../trailing_commas/ >trailing commas</a>.</p> <h2 id=sax-vs-dom-parsing><abbr title="Simple API for XML">SAX</abbr> vs. <abbr title="Document Object Model">DOM</abbr> parsing<a class=headerlink href=#sax-vs-dom-parsing title="Permanent link">&para;</a></h2> <p>The library offers two parsing models:</p> <ul> <li><strong><abbr title="Document Object Model">DOM</abbr> parsing</strong> (the default): the complete input is read and stored as an in-memory <code>basic_json</code> value that can be traversed and modified freely. This is what <a href=../../api/basic_json/parse/ ><code>parse</code></a> does, and it is the right choice for most use cases.</li> <li><strong><abbr title="Simple API for XML">SAX</abbr> parsing</strong>: instead of building a value, the parser reports events (such as "a string was read" or "an object started") to a handler that you implement. This avoids building the full value in memory and is useful for very large inputs or when you only need to extract parts of the input. See the <a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> for details and <a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> for the <abbr title="Application Programming Interfaces">API</abbr>.</li> </ul> <p>You can influence a <abbr title="Document Object Model">DOM</abbr> parse without switching to the <abbr title="Simple API for XML">SAX</abbr> interface by passing a <a href=parser_callbacks/ >parser callback</a>, which is called during parsing and can, for example, discard parts of the input.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <p>When the input is not valid <abbr title="JavaScript Object Notation">JSON</abbr>, the <code>parse</code> function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or <a href=../../api/basic_json/accept/ ><code>accept</code></a> can be used to only check whether an input is valid <abbr title="JavaScript Object Notation">JSON</abbr>. See <a href=parse_exceptions/ >parsing and exceptions</a> for the available options.</p> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/parse/ ><code>parse</code></a> - deserialize from a compatible input</li> <li><a href=../../api/basic_json/accept/ ><code>accept</code></a> - check if the input is valid <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=../../api/basic_json/sax_parse/ ><code>sax_parse</code></a> - generate <abbr title="Simple API for XML">SAX</abbr> events</li> <li><a href=json_lines/ ><abbr title="JavaScript Object Notation">JSON</abbr> Lines</a> - parse newline-delimited <abbr title="JavaScript Object Notation">JSON</abbr></li> <li><a href=parser_callbacks/ >parser callbacks</a> - influence the parsing by a callback function</li> <li><a href=sax_interface/ ><abbr title="Simple API for XML">SAX</abbr> interface</a> - implement a custom <abbr title="Simple API for XML">SAX</abbr> handler</li> <li><a href=parse_exceptions/ >parsing and exceptions</a> - control error handling</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="July 9, 2026 15:15:57 UTC">July 9, 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.sliceLine truncated