Deployed d8a63291 with MkDocs version: 1.2.3

features/arbitrary_types/index.html

@@ -50,7 +50,7 @@
 <span class=w>        </span><span class=n>j</span><span class=p>.</span><span class=n>at</span><span class=p>(</span><span class=s>&quot;age&quot;</span><span class=p>).</span><span class=n>get_to</span><span class=p>(</span><span class=n>p</span><span class=p>.</span><span class=n>age</span><span class=p>);</span><span class=w></span>
 <span class=w>    </span><span class=p>}</span><span class=w></span>
 <span class=p>}</span><span class=w> </span><span class=c1>// namespace ns</span>
-</code></pre></div> <p>That's all! When calling the <code>json</code> constructor with your type, your custom <code>to_json</code> method will be automatically called. Likewise, when calling <code>get&lt;your_type&gt;()</code> or <code>get_to(your_type&amp;)</code>, the <code>from_json</code> method will be called.</p> <p>Some important things:</p> <ul> <li>Those methods <strong>MUST</strong> be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace <code>ns</code>, where <code>person</code> is defined).</li> <li>Those methods <strong>MUST</strong> be available (e.g., proper headers must be included) everywhere you use these conversions. Look at <a href=https://github.com/nlohmann/json/issues/1108>issue 1108</a> for errors that may occur otherwise.</li> <li>When using <code>get&lt;your_type&gt;()</code>, <code>your_type</code> <strong>MUST</strong> be <a href=https://en.cppreference.com/w/cpp/named_req/DefaultConstructible>DefaultConstructible</a>. (There is a way to bypass this requirement described later.)</li> <li>In function <code>from_json</code>, use function <a href=https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c><code>at()</code></a> to access the object values rather than <code>operator[]</code>. In case a key does not exist, <code>at</code> throws an exception that you can handle, whereas <code>operator[]</code> exhibits undefined behavior.</li> <li>You do not need to add serializers or deserializers for STL types like <code>std::vector</code>: the library already implements these.</li> </ul> <h2 id=simplify-your-life-with-macros>Simplify your life with macros<a class=headerlink href=#simplify-your-life-with-macros title="Permanent link">&para;</a></h2> <p>If you just want to serialize/deserialize some structs, the <code>to_json</code>/<code>from_json</code> functions can be a lot of boilerplate.</p> <p>There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:</p> <ul> <li><code>NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)</code> is to be defined inside the namespace of the class/struct to create code for.</li> <li><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)</code> is to be defined inside the class/struct to create code for. This macro can also access private members.</li> </ul> <p>In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>At most 64 member variables can be passed to <code>NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE</code> or <code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code>.</p> </div> <details class=example> <summary>Example</summary> <p>The <code>to_json</code>/<code>from_json</code> functions for the <code>person</code> struct above can be created with:</p> <div class=highlight><pre><span></span><code><span class=k>namespace</span><span class=w> </span><span class=nn>ns</span><span class=w> </span><span class=p>{</span><span class=w></span>
+</code></pre></div> <p>That's all! When calling the <code>json</code> constructor with your type, your custom <code>to_json</code> method will be automatically called. Likewise, when calling <code>get&lt;your_type&gt;()</code> or <code>get_to(your_type&amp;)</code>, the <code>from_json</code> method will be called.</p> <p>Some important things:</p> <ul> <li>Those methods <strong>MUST</strong> be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace <code>ns</code>, where <code>person</code> is defined).</li> <li>Those methods <strong>MUST</strong> be available (e.g., proper headers must be included) everywhere you use these conversions. Look at <a href=https://github.com/nlohmann/json/issues/1108>issue 1108</a> for errors that may occur otherwise.</li> <li>When using <code>get&lt;your_type&gt;()</code>, <code>your_type</code> <strong>MUST</strong> be <a href=https://en.cppreference.com/w/cpp/named_req/DefaultConstructible>DefaultConstructible</a>. (There is a way to bypass this requirement described later.)</li> <li>In function <code>from_json</code>, use function <a href=https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c><code>at()</code></a> to access the object values rather than <code>operator[]</code>. In case a key does not exist, <code>at</code> throws an exception that you can handle, whereas <code>operator[]</code> exhibits undefined behavior.</li> <li>You do not need to add serializers or deserializers for STL types like <code>std::vector</code>: the library already implements these.</li> </ul> <h2 id=simplify-your-life-with-macros>Simplify your life with macros<a class=headerlink href=#simplify-your-life-with-macros title="Permanent link">&para;</a></h2> <p>If you just want to serialize/deserialize some structs, the <code>to_json</code>/<code>from_json</code> functions can be a lot of boilerplate.</p> <p>There are four macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:</p> <ul> <li><code>NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)</code> is to be defined inside the namespace of the class/struct to create code for. It will throw an exception in <code>from_json()</code> due to a missing value in the JSON object.</li> <li><code>NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(name, member1, member2, ...)</code> is to be defined inside the namespace of the class/struct to create code for. It will not throw an exception in <code>from_json()</code> due to a missing value in the JSON object, but fills in values from object which is default-constructed by the type.</li> <li><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)</code> is to be defined inside the class/struct to create code for. This macro can also access private members. It will throw an exception in <code>from_json()</code> due to a missing value in the JSON object.</li> <li><code>NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(name, member1, member2, ...)</code> is to be defined inside the class/struct to create code for. This macro can also access private members. It will not throw an exception in <code>from_json()</code> due to a missing value in the JSON object, but fills in values from object which is default-constructed by the type.</li> </ul> <p>In all macros, the first parameter is the name of the class/struct, and all remaining parameters name the members. You can read more docs about them starting from <a href=../macros/#nlohmann_define_type_intrusivetype-member>here</a>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>At most 64 member variables can be passed to these macros.</p> </div> <details class=example> <summary>Example</summary> <p>The <code>to_json</code>/<code>from_json</code> functions for the <code>person</code> struct above can be created with:</p> <div class=highlight><pre><span></span><code><span class=k>namespace</span><span class=w> </span><span class=nn>ns</span><span class=w> </span><span class=p>{</span><span class=w></span>
 <span class=w>    </span><span class=n>NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE</span><span class=p>(</span><span class=n>person</span><span class=p>,</span><span class=w> </span><span class=n>name</span><span class=p>,</span><span class=w> </span><span class=n>address</span><span class=p>,</span><span class=w> </span><span class=n>age</span><span class=p>)</span><span class=w></span>
 <span class=p>}</span><span class=w></span>
 </code></pre></div> <p>Here is an example with private members, where <code>NLOHMANN_DEFINE_TYPE_INTRUSIVE</code> is needed:</p> <div class=highlight><pre><span></span><code><span class=k>namespace</span><span class=w> </span><span class=nn>ns</span><span class=w> </span><span class=p>{</span><span class=w></span>