External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
55f10f44a9
json/features/enum_conversion/index.html

27 lines
56 KiB
HTML
Raw Normal View History

Deployed fe4b663 with MkDocs version: 1.4.2
2023-03-08 15:43:29 +03:00
<!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/enum_conversion/ rel=canonical><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.4.2, mkdocs-material-8.5.10"><title>Specializing enum conversion - 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=#specializing-enum-conversion 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> Specializing enum conversion </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-2.42-1.44-4.5-3.5-5.45C10.26 6
<span class=k>enum</span><span class=w> </span><span class=nc>TaskState</span><span class=w> </span><span class=p>{</span><span class=w></span>
<span class=w> </span><span class=n>TS_STOPPED</span><span class=p>,</span><span class=w></span>
<span class=w> </span><span class=n>TS_RUNNING</span><span class=p>,</span><span class=w></span>
<span class=w> </span><span class=n>TS_COMPLETED</span><span class=p>,</span><span class=w></span>
<span class=w> </span><span class=n>TS_INVALID</span><span class=o>=</span><span class=mi>-1</span><span class=p>,</span><span class=w></span>
<span class=p>};</span><span class=w></span>
<span class=c1>// map TaskState values to JSON as strings</span>
<span class=n>NLOHMANN_JSON_SERIALIZE_ENUM</span><span class=p>(</span><span class=w> </span><span class=n>TaskState</span><span class=p>,</span><span class=w> </span><span class=p>{</span><span class=w></span>
<span class=w> </span><span class=p>{</span><span class=n>TS_INVALID</span><span class=p>,</span><span class=w> </span><span class=k>nullptr</span><span class=p>},</span><span class=w></span>
<span class=w> </span><span class=p>{</span><span class=n>TS_STOPPED</span><span class=p>,</span><span class=w> </span><span class=s>&quot;stopped&quot;</span><span class=p>},</span><span class=w></span>
<span class=w> </span><span class=p>{</span><span class=n>TS_RUNNING</span><span class=p>,</span><span class=w> </span><span class=s>&quot;running&quot;</span><span class=p>},</span><span class=w></span>
<span class=w> </span><span class=p>{</span><span class=n>TS_COMPLETED</span><span class=p>,</span><span class=w> </span><span class=s>&quot;completed&quot;</span><span class=p>},</span><span class=w></span>
<span class=p>})</span><span class=w></span>
</code></pre></div> <p>The <a href=../../api/macros/nlohmann_json_serialize_enum/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM()</code> macro</a> declares a set of <code>to_json()</code> / <code>from_json()</code> functions for type <code>TaskState</code> while avoiding repetition and boilerplate serialization code.</p> <h2 id=usage>Usage<a class=headerlink href=#usage title="Permanent link">&para;</a></h2> <div class=highlight><pre><span></span><code><span class=c1>// enum to JSON as string</span>
<span class=n>json</span><span class=w> </span><span class=n>j</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>TS_STOPPED</span><span class=p>;</span><span class=w></span>
<span class=n>assert</span><span class=p>(</span><span class=n>j</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=s>&quot;stopped&quot;</span><span class=p>);</span><span class=w></span>
<span class=c1>// json string to enum</span>
<span class=n>json</span><span class=w> </span><span class=n>j3</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s>&quot;running&quot;</span><span class=p>;</span><span class=w></span>
<span class=n>assert</span><span class=p>(</span><span class=n>j3</span><span class=p>.</span><span class=n>get</span><span class=o>&lt;</span><span class=n>TaskState</span><span class=o>&gt;</span><span class=p>()</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>TS_RUNNING</span><span class=p>);</span><span class=w></span>
<span class=c1>// undefined json value to enum (where the first map entry above is the default)</span>
<span class=n>json</span><span class=w> </span><span class=n>jPi</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=mf>3.14</span><span class=p>;</span><span class=w></span>
<span class=n>assert</span><span class=p>(</span><span class=n>jPi</span><span class=p>.</span><span class=n>get</span><span class=o>&lt;</span><span class=n>TaskState</span><span class=o>&gt;</span><span class=p>()</span><span class=w> </span><span class=o>==</span><span class=w> </span><span class=n>TS_INVALID</span><span class=w> </span><span class=p>);</span><span class=w></span>
</code></pre></div> <h2 id=notes>Notes<a class=headerlink href=#notes title="Permanent link">&para;</a></h2> <p>Just as in <a href=../arbitrary_types/ >Arbitrary Type Conversions</a> above,</p> <ul> <li><a href=../../api/macros/nlohmann_json_serialize_enum/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM()</code></a> MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.</li> <li>It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.</li> </ul> <p>Other Important points:</p> <ul> <li>When using <code>get&lt;ENUM_TYPE&gt;()</code>, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.</li> <li>If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.</li> <li>To disable the default serialization of enumerators as integers and force a compiler error instead, see <a href=../../api/macros/json_disable_enum_serialization/ ><code>JSON_DISABLE_ENUM_SERIALIZATION</code></a>.</li> </ul> <hr> <div class=md-source-file> <small> Last update: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">March 8, 2023</span> </small> </div> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var tab,labels=set.querySelector(".tabbed-labels");for(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> </div> <a href=# 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 8v12Z"/></svg> Back to top </a> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../assertions/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Runtime Assertions" rel=prev> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </div> <div class=md-footer__title> <div class=md-ellipsis> <span class=md-footer__direction> Previous </span> Runtime Assertions </div> </div> </a> <a href=../macros/ class="md-footer__link md-footer__link--next" aria-label="Next: Supported Macros" rel=next> <div class=md-footer__title> <div class=md-ellipsis> <span class=md-footer__direction> Next </span> Supported Macros </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4Z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013 - 2022 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 496 512"><!-- Font Awesome Free 6.2.1 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 2022 Fonticons, Inc.--><path d="M165.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.6zm-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.3zm44.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.9zM244.8 8C106.1 8 0 113.3 0 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 7
Reference in New Issue Copy Permalink