22 lines
64 KiB
HTML
22 lines
64 KiB
HTML
|
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=author content="Niels Lohmann"><link href=https://json.nlohmann.me/features/element_access/unchecked_access/ rel=canonical><link rel=icon href=../../../assets/images/favicon.png><meta name=generator content="mkdocs-1.4.2, mkdocs-material-8.5.10"><title>Unchecked access: operator[] - JSON for Modern C++</title><link rel=stylesheet href=../../../assets/stylesheets/main.975780f9.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.2505c338.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CJetBrains+Mono:400,400i,700,700i&display=fallback"><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> <script>var palette=__md_get("__palette");if(palette&&"object"==typeof palette.color)for(var key of Object.keys(palette.color))document.body.setAttribute("data-md-color-"+key,palette.color[key])</script> <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=#unchecked-access-operator 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.54Z"/></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 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></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> Unchecked access: operator[] </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_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 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 12 20 8.69Z"/></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_2> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 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 12c0
|
||
|
|
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"Mary Smith"</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"age"</span><span class=p>:</span><span class=w> </span><span class=mi>42</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"hobbies"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"hiking"</span><span class=p>,</span><span class=w> </span><span class=s2>"reading"</span><span class=p>]</span><span class=w></span>
|
||
|
|
<span class=p>}</span><span class=w></span>
|
||
|
|
</code></pre></div> <p>Assume the value is parsed to a <code>json</code> variable <code>j</code>.</p> <table> <thead> <tr> <th>expression</th> <th>value</th> </tr> </thead> <tbody> <tr> <td><code class=highlight><span class=n>j</span><span class=w></span></code></td> <td><code class=highlight><span class=p>{</span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"Mary Smith"</span><span class=p>,</span><span class=w> </span><span class=nt>"age"</span><span class=p>:</span><span class=w> </span><span class=mi>42</span><span class=p>,</span><span class=w> </span><span class=nt>"hobbies"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"hiking"</span><span class=p>,</span><span class=w> </span><span class=s2>"reading"</span><span class=p>]}</span><span class=w></span></code></td> </tr> <tr> <td><code class=highlight><span class=n>j</span><span class=p>[</span><span class=s>"name"</span><span class=p>]</span><span class=w></span></code></td> <td><code class=highlight><span class=s2>"Mary Smith"</span><span class=w></span></code></td> </tr> <tr> <td><code class=highlight><span class=n>j</span><span class=p>[</span><span class=s>"age"</span><span class=p>]</span><span class=w></span></code></td> <td><code class=highlight><span class=mi>42</span><span class=w></span></code></td> </tr> <tr> <td><code class=highlight><span class=n>j</span><span class=p>[</span><span class=s>"hobbies"</span><span class=p>]</span><span class=w></span></code></td> <td><code class=highlight><span class=p>[</span><span class=s2>"hiking"</span><span class=p>,</span><span class=w> </span><span class=s2>"reading"</span><span class=p>]</span><span class=w></span></code></td> </tr> <tr> <td><code class=highlight><span class=n>j</span><span class=p>[</span><span class=s>"hobbies"</span><span class=p>][</span><span class=mi>0</span><span class=p>]</span><span class=w></span></code></td> <td><code class=highlight><span class=s2>"hiking"</span><span class=w></span></code></td> </tr> <tr> <td><code class=highlight><span class=n>j</span><span class=p>[</span><span class=s>"hobbies"</span><span class=p>][</span><span class=mi>1</span><span class=p>]</span><span class=w></span></code></td> <td><code class=highlight><span class=s2>"reading"</span><span class=w></span></code></td> </tr> </tbody> </table> </details> <p>The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a <code class=highlight><span class=kc>null</span><span class=w></span></code> value is inserted which can be immediately be overwritten.</p> <details class=example> <summary>Write access</summary> <div class=highlight><pre><span></span><code><span class=n>j</span><span class=p>[</span><span class=s>"name"</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"John Smith"</span><span class=p>;</span><span class=w></span>
|
||
|
|
<span class=n>j</span><span class=p>[</span><span class=s>"maidenName"</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"Jones"</span><span class=p>;</span><span class=w></span>
|
||
|
|
</code></pre></div> <p>This code produces the following JSON value:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"John Smith"</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"maidenName"</span><span class=p>:</span><span class=w> </span><span class=s2>"Jones"</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"age"</span><span class=p>:</span><span class=w> </span><span class=mi>42</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"hobbies"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"hiking"</span><span class=p>,</span><span class=w> </span><span class=s2>"reading"</span><span class=p>]</span><span class=w></span>
|
||
|
|
<span class=p>}</span><span class=w></span>
|
||
|
|
</code></pre></div> </details> <p>When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such that the passed index is the new maximal index. Intermediate values are filled with <code class=highlight><span class=kc>null</span><span class=w></span></code>.</p> <details class=example> <summary>Filling up arrays with <code class=highlight><span class=kc>null</span><span class=w></span></code> values</summary> <div class=highlight><pre><span></span><code><span class=n>j</span><span class=p>[</span><span class=s>"hobbies"</span><span class=p>][</span><span class=mi>0</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"running"</span><span class=p>;</span><span class=w></span>
|
||
|
|
<span class=n>j</span><span class=p>[</span><span class=s>"hobbies"</span><span class=p>][</span><span class=mi>3</span><span class=p>]</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>"cooking"</span><span class=p>;</span><span class=w></span>
|
||
|
|
</code></pre></div> <p>This code produces the following JSON value:</p> <div class=highlight><pre><span></span><code><span class=p>{</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"John Smith"</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"maidenName"</span><span class=p>:</span><span class=w> </span><span class=s2>"Jones"</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"age"</span><span class=p>:</span><span class=w> </span><span class=mi>42</span><span class=p>,</span><span class=w></span>
|
||
|
|
<span class=w> </span><span class=nt>"hobbies"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"running"</span><span class=p>,</span><span class=w> </span><span class=s2>"reading"</span><span class=p>,</span><span class=w> </span><span class=kc>null</span><span class=p>,</span><span class=w> </span><span class=s2>"cooking"</span><span class=p>]</span><span class=w></span>
|
||
|
|
<span class=p>}</span><span class=w></span>
|
||
|
|
</code></pre></div> </details> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">¶</a></h2> <div class="admonition info"> <p class=admonition-title>Design rationale</p> <p>The library behaves differently to <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=w></span></code> and <code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=w></span></code>:</p> <ul> <li><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>vector</span><span class=o>::</span><span class=k>operator</span><span class=p>[]</span><span class=w></span></code> never inserts a new element.</li> <li><code class=highlight><span class=n>std</span><span class=o>::</span><span class=n>map</span><span class=o>::</span><span class=k>operator</span><span class=p>[]</span><span class=w></span></code> is not available for const values.</li> </ul> <p>The type <code class=highlight><span class=n>json</span><span class=w></span></code> wraps all JSON value types. It would be impossible to remove <a href=../../../api/basic_json/operator%5B%5D/ ><code>operator[]</code></a> for const objects. At the same time, inserting elements for non-const objects is really convenient as it avoids awkward <code>insert</code> calls. To this end, we decided to have an inserting non-const behavior for both arrays and objects.</p> </div> <div class="admonition info"> <p class=admonition-title>Info</p> <p>The access is unchecked. In case the passed object key does not exist or the passed array index is invalid, no exception is thrown.</p> </div> <div class="admonition danger"> <p class=admonition-title>Danger</p> <ul> <li>It is <strong>undefined behavior</strong> to access a const object with a non-existing key.</li> <li>It is <strong>undefined behavior</strong> to access a const array with an invalid index.</li> <li>In debug mode, an <strong>assertion</strong> will fire in both cases. You can disable assertions by defining the preprocessor symbol <code class=highlight><span class=n>NDEBUG</span><span class=w></span></code> or redefine the macro <a href=../../macros/#json_assertx><code>JSON_ASSERT(x)</code></a>. See the documentation on <a href=../../assertions/ >runtime assertions</a> for more information.</li> </ul> </div> <div class="admonition failure"> <p class=admonition-title>Exceptions</p> <p><code>operator[]</code> can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a <a href=../../../home/exceptions/#jsonexceptiontype_error305><code>basic_json::type_error</code></a> is thrown.</p> </div> <h2 id=summary>Summary<a class=headerlink href=#summary title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>scenario</th> <th>non-const value</th> <th>const value</th> </tr> </thead> <tbody> <tr> <td>access to existing object key</td> <td>reference to existing value is returned</td> <td>const reference to existing value is returned</td> </tr> <tr> <td>access to valid array index</td> <td>reference to existing value is returned</td> <td>const reference to existing value is returned</td> </tr> <tr> <td>access to non-existing object key</td> <td>reference to newly inserted <code class=highlight><span class=kc>null</span><span class=w></span></code> value is returned</td> <td><strong>undefined behavior</strong>; <a href=../../assertions/ >runtime assertion</a> in debug mode</td> </tr> <tr> <td>access to invalid array index</td> <td>reference to newly inserted <code class=highlight><span class=kc>null</span><span class=w></span></code> value is returned; any index between previous maximal index and passed index are filled with <code class=highlight><span class=kc>null</span><span class=w></span></code></td> <td><strong>undefined behavior</strong>; <a href=../../assertions/ >runtime assertion</a> in debug mode</td> </tr> </tbody> </table> <hr> <div class=md-source-file> <small> Last update: <span class="git-revision-date-localized-plugin git-revision-date-localized
|