deploy: ca76c37650

api/basic_json/from_bson/index.html

@@ -4,11 +4,11 @@
 <span class=w>                            </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>strict</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>,</span>
 <span class=w>                            </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>allow_exceptions</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>);</span>
 <span class=c1>// (2)</span>
-<span class=k>template</span><span class=o>&lt;</span><span class=k>typename</span><span class=w> </span><span class=nc>IteratorType</span><span class=o>&gt;</span>
-<span class=k>static</span><span class=w> </span><span class=n>basic_json</span><span class=w> </span><span class=n>from_bson</span><span class=p>(</span><span class=n>IteratorType</span><span class=w> </span><span class=n>first</span><span class=p>,</span><span class=w> </span><span class=n>IteratorType</span><span class=w> </span><span class=n>last</span><span class=p>,</span>
+<span class=k>template</span><span class=o>&lt;</span><span class=k>typename</span><span class=w> </span><span class=nc>IteratorType</span><span class=p>,</span><span class=w> </span><span class=k>typename</span><span class=w> </span><span class=nc>SentinelType</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>IteratorType</span><span class=o>&gt;</span>
+<span class=k>static</span><span class=w> </span><span class=n>basic_json</span><span class=w> </span><span class=n>from_bson</span><span class=p>(</span><span class=n>IteratorType</span><span class=w> </span><span class=n>first</span><span class=p>,</span><span class=w> </span><span class=n>SentinelType</span><span class=w> </span><span class=n>last</span><span class=p>,</span>
 <span class=w>                            </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>strict</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>,</span>
 <span class=w>                            </span><span class=k>const</span><span class=w> </span><span class=kt>bool</span><span class=w> </span><span class=n>allow_exceptions</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nb>true</span><span class=p>);</span>
-</code></pre></div> <p>Deserializes a given input to a <abbr title="JavaScript Object Notation">JSON</abbr> value using the <abbr title="Binary JSON">BSON</abbr> (Binary <abbr title="JavaScript Object Notation">JSON</abbr>) serialization format.</p> <ol> <li>Reads from a compatible input.</li> <li>Reads from an iterator range.</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bson/ >dedicated page</a>.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code>FILE</code> pointer</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters</li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd>a compatible iterator type</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>an input in <abbr title="Binary JSON">BSON</abbr> format convertible to an input adapter</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of the input</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the input</dd> <dt><code>strict</code> (in)</dt> <dd>whether to expect the input to be consumed until <abbr title="End of File">EOF</abbr> (<code class=highlight><span class=nb>true</span></code> by default)</dd> <dt><code>allow_exceptions</code> (in)</dt> <dd>whether to throw exceptions in case of a parse error (optional, <code class=highlight><span class=nb>true</span></code> by default)</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>deserialized <abbr title="JavaScript Object Notation">JSON</abbr> value; in case of a parse error and <code>allow_exceptions</code> set to <code class=highlight><span class=nb>false</span></code>, the return value will be <code>value_t::discarded</code>. The latter can be checked with <a href=../is_discarded/ ><code>is_discarded</code></a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error110><code>parse_error.110</code></a> if the given input ends prematurely or the end of the input was not reached when <code>strict</code> was set to true</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error112><code>parse_error.112</code></a> if a parse error occurs (e.g., an invalid string or byte array length)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error114><code>parse_error.114</code></a> if an unsupported <abbr title="Binary JSON">BSON</abbr> record type is encountered</li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the input.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the deserialization of a byte vector in <abbr title="Binary JSON">BSON</abbr> format to a <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <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> <p>Deserializes a given input to a <abbr title="JavaScript Object Notation">JSON</abbr> value using the <abbr title="Binary JSON">BSON</abbr> (Binary <abbr title="JavaScript Object Notation">JSON</abbr>) serialization format.</p> <ol> <li>Reads from a compatible input.</li> <li>Reads from an iterator range, or an iterator and a sentinel of a different type (C++20 ranges support).</li> </ol> <p>The exact mapping and its limitations are described on a <a href=../../../features/binary_formats/bson/ >dedicated page</a>.</p> <h2 id=template-parameters>Template parameters<a class=headerlink href=#template-parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>InputType</code></dt> <dd> <p>A compatible input, for instance:</p> <ul> <li>an <code>std::istream</code> object</li> <li>a <code>FILE</code> pointer</li> <li>a C-style array of characters</li> <li>a pointer to a null-terminated string of single byte characters</li> <li>a container <code>obj</code> for which <code>begin(obj)</code> and <code>end(obj)</code> produce a valid pair of iterators (as found via <abbr title="Argument-dependent lookup">ADL</abbr> or member functions, with semantics compatible to <code>std::begin</code> and <code>std::end</code>)</li> </ul> </dd> <dt><code>IteratorType</code></dt> <dd>a compatible iterator type</dd> <dt><code>SentinelType</code></dt> <dd>defaults to <code>IteratorType</code>; may be a different type comparable to <code>IteratorType</code> via <code>operator!=</code>, for instance a custom sentinel type for C++20 ranges</dd> </dl> <h2 id=parameters>Parameters<a class=headerlink href=#parameters title="Permanent link">&para;</a></h2> <dl> <dt><code>i</code> (in)</dt> <dd>an input in <abbr title="Binary JSON">BSON</abbr> format convertible to an input adapter</dd> <dt><code>first</code> (in)</dt> <dd>iterator to the start of the input</dd> <dt><code>last</code> (in)</dt> <dd>iterator to the end of the input, or a sentinel value that compares equal to the end iterator with <code>operator!=</code></dd> <dt><code>strict</code> (in)</dt> <dd>whether to expect the input to be consumed until <abbr title="End of File">EOF</abbr> (<code class=highlight><span class=nb>true</span></code> by default)</dd> <dt><code>allow_exceptions</code> (in)</dt> <dd>whether to throw exceptions in case of a parse error (optional, <code class=highlight><span class=nb>true</span></code> by default)</dd> </dl> <h2 id=return-value>Return value<a class=headerlink href=#return-value title="Permanent link">&para;</a></h2> <p>deserialized <abbr title="JavaScript Object Notation">JSON</abbr> value; in case of a parse error and <code>allow_exceptions</code> set to <code class=highlight><span class=nb>false</span></code>, the return value will be <code>value_t::discarded</code>. The latter can be checked with <a href=../is_discarded/ ><code>is_discarded</code></a>.</p> <h2 id=exception-safety>Exception safety<a class=headerlink href=#exception-safety title="Permanent link">&para;</a></h2> <p>Strong guarantee: if an exception is thrown, there are no changes in the <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <h2 id=exceptions>Exceptions<a class=headerlink href=#exceptions title="Permanent link">&para;</a></h2> <ul> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error110><code>parse_error.110</code></a> if the given input ends prematurely or the end of the input was not reached when <code>strict</code> was set to true</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error112><code>parse_error.112</code></a> if a parse error occurs (e.g., an invalid string or byte array length)</li> <li>Throws <a href=../../../home/exceptions/#jsonexceptionparse_error114><code>parse_error.114</code></a> if an unsupported <abbr title="Binary JSON">BSON</abbr> record type is encountered</li> </ul> <h2 id=complexity>Complexity<a class=headerlink href=#complexity title="Permanent link">&para;</a></h2> <p>Linear in the size of the input.</p> <h2 id=examples>Examples<a class=headerlink href=#examples title="Permanent link">&para;</a></h2> <details class=example> <summary>Example</summary> <p>The example shows the deserialization of a byte vector in <abbr title="Binary JSON">BSON</abbr> format to a <abbr title="JavaScript Object Notation">JSON</abbr> value.</p> <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;iomanip&gt;</span>
 <span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
 
@@ -33,4 +33,4 @@
 <span class=w>  </span><span class=nt>&quot;compact&quot;</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>,</span>
 <span class=w>  </span><span class=nt>&quot;schema&quot;</span><span class=p>:</span><span class=w> </span><span class=mi>0</span>
 <span class=p>}</span>
-</code></pre></div> </details> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href="http://bsonspec.org/spec.html"><abbr title="Binary JSON">BSON</abbr> specification</a></li> <li><a href=../to_bson/ >to_bson</a> for the analogous serialization</li> <li><a href=../from_cbor/ >from_cbor</a> for the related <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> <li><a href=../from_msgpack/ >from_msgpack</a> for the related MessagePack format</li> <li><a href=../from_ubjson/ >from_ubjson</a> for the related <abbr title="Universal Binary JSON">UBJSON</abbr> format</li> <li><a href=../from_bjdata/ >from_bjdata</a> for the related <abbr title="Binary JData">BJData</abbr> format</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.4.0.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <ul> <li>Overload (2) replaces calls to <code>from_bson</code> with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</li> <li>Overload (2) replaces calls to <code>from_bson</code> with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>from_bson</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</li> </ul> <p>You should be warned by your compiler with a <code>-Wdeprecated-declarations</code> warning if you are using a deprecated function.</p> </div> <!-- 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 11, 2026 13:09:05 UTC">July 11, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by 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="http://bsonspec.org/spec.html"><abbr title="Binary JSON">BSON</abbr> specification</a></li> <li><a href=../to_bson/ >to_bson</a> for the analogous serialization</li> <li><a href=../from_cbor/ >from_cbor</a> for the related <abbr title="Concise Binary Object Representation">CBOR</abbr> format</li> <li><a href=../from_msgpack/ >from_msgpack</a> for the related MessagePack format</li> <li><a href=../from_ubjson/ >from_ubjson</a> for the related <abbr title="Universal Binary JSON">UBJSON</abbr> format</li> <li><a href=../from_bjdata/ >from_bjdata</a> for the related <abbr title="Binary JData">BJData</abbr> format</li> </ul> <h2 id=version-history>Version history<a class=headerlink href=#version-history title="Permanent link">&para;</a></h2> <ul> <li>Added in version 3.4.0.</li> <li>Extended container support (1) to include types with lvalue-only <abbr title="Argument-dependent lookup">ADL</abbr> <code>begin</code>/<code>end</code> (matching <code>std::begin</code>/<code>std::end</code> semantics) in version 3.13.0.</li> <li>Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.</li> </ul> <div class="admonition warning"> <p class=admonition-title>Deprecation</p> <ul> <li>Overload (2) replaces calls to <code>from_bson</code> with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</li> <li>Overload (2) replaces calls to <code>from_bson</code> with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like <code class=highlight><span class=n>from_bson</span><span class=p>({</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>},</span><span class=w> </span><span class=p>...);</span></code> with <code class=highlight><span class=n>from_bson</span><span class=p>(</span><span class=n>ptr</span><span class=p>,</span><span class=w> </span><span class=n>ptr</span><span class=o>+</span><span class=n>len</span><span class=p>,</span><span class=w> </span><span class=p>...);</span></code>.</li> </ul> <p>You should be warned by your compiler with a <code>-Wdeprecated-declarations</code> warning if you are using a deprecated function.</p> </div> <!-- 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 11, 2026 13:09:28 UTC">July 11, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.cLine truncated