</code></pre></div><p>Type <code>json</code> is an alias for <code>basic_json<></code> and uses the default types.</p><p>From the template arguments, the following types are derived:</p><divclass=highlight><pre><span></span><code><spanclass=k>using</span><spanclass=w></span><spanclass=n>object_comparator_t</span><spanclass=w></span><spanclass=o>=</span><spanclass=w></span><spanclass=n>std</span><spanclass=o>::</span><spanclass=n>less</span><spanclass=o><></span><spanclass=p>;</span><spanclass=w></span>
</code></pre></div><h2id=objects>Objects<aclass=headerlinkhref=#objectstitle="Permanent link">¶</a></h2><p><ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a> describes JSON objects as follows:</p><blockquote><p>An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.</p></blockquote><h3id=default-type>Default type<aclass=headerlinkhref=#default-typetitle="Permanent link">¶</a></h3><p>With the default values for <em>ObjectType</em> (<code>std::map</code>), <em>StringType</em> (<code>std::string</code>), and <em>AllocatorType</em> (<code>std::allocator</code>), the default value for <code>object_t</code> is:</p><divclass=highlight><pre><span></span><code><spanclass=n>std</span><spanclass=o>::</span><spanclass=n>map</span><spanclass=o><</span><spanclass=w></span>
</code></pre></div><h3id=behavior>Behavior<aclass=headerlinkhref=#behaviortitle="Permanent link">¶</a></h3><p>The choice of <code>object_t</code> influences the behavior of the JSON class. With the default type, objects have the following behavior:</p><ul><li>When all names are unique, objects will be interoperable in the sense that all software implementations receiving that object will agree on the name-value mappings.</li><li>When the names within an object are not unique, it is unspecified which one of the values for a given key will be chosen. For instance, <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"key"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"key"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>}</span><spanclass=w></span></code> could be equal to either <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"key"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>}</span><spanclass=w></span></code> or <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"key"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>}</span><spanclass=w></span></code>.</li><li>Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see <code>dump</code>) in this order. For instance, both <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"b"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"a"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>}</span><spanclass=w></span></code> and <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"a"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"b"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>}</span><spanclass=w></span></code> will be stored and serialized as <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"a"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"b"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>}</span><spanclass=w></span></code>.</li><li>When comparing objects, the order of the name/value pairs is irrelevant. This makes objects interoperable in the sense that they will not be affected by these differences. For instance, <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"b"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"a"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>}</span><spanclass=w></span></code> and <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"a"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"b"</span><spanclass=p>:</span><spanclass=w></span><spanclass=mi>1</span><spanclass=p>}</span><spanclass=w></span></code> will be treated as equal.</li></ul><h3id=key-order>Key order<aclass=headerlinkhref=#key-ordertitle="Permanent link">¶</a></h3><p>The order name/value pairs are added to the object is <em>not</em> preserved by the library. Therefore, iterating an object may return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in alphabetical order as <code>std::map</code> with <code>std::less</code> is used by default. Please note this behavior conforms to <ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a>, because any order implements the spec
</code></pre></div><h3id=limits_1>Limits<aclass=headerlinkhref=#limits_1title="Permanent link">¶</a></h3><p><ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a> specifies:</p><blockquote><p>An implementation may set limits on the maximum depth of nesting.</p></blockquote><p>In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the <code>max_size</code> function of a JSON array.</p><h3id=storage_2>Storage<aclass=headerlinkhref=#storage_2title="Permanent link">¶</a></h3><p>Arrays are stored as pointers in a <code>basic_json</code> type. That is, for any access to array values, a pointer of type <code>array_t*</code> must be dereferenced.</p><h2id=strings>Strings<aclass=headerlinkhref=#stringstitle="Permanent link">¶</a></h2><p><ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a> describes JSON strings as follows:</p><blockquote><p>A string is a sequence of zero or more Unicode characters.</p></blockquote><p>Unicode values are split by the JSON class into byte-sized characters during deserialization.</p><h3id=default-type_2>Default type<aclass=headerlinkhref=#default-type_2title="Permanent link">¶</a></h3><p>With the default values for <em>StringType</em> (<code>std::string</code>), the default value for <code>string_t</code> is <codeclass=highlight><spanclass=n>std</span><spanclass=o>::</span><spanclass=n>string</span><spanclass=w></span></code>.</p><h3id=encoding>Encoding<aclass=headerlinkhref=#encodingtitle="Permanent link">¶</a></h3><p>Strings are stored in UTF-8 encoding. Therefore, functions like <code>std::string::size()</code> or <code>std::string::length()</code> return the number of <strong>bytes</strong> in the string rather than the number of characters or glyphs.</p><h3id=string-comparison>String comparison<aclass=headerlinkhref=#string-comparisontitle="Permanent link">¶</a></h3><p><ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a> states:</p><blockquote><p>Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that <code>"a\\b"</code> and <code>"a\u005Cb"</code> are not equal.</p></blockquote><p>This implementation is interoperable as it does compare strings code unit by code unit.</p><h3id=storage_3>Storage<aclass=headerlinkhref=#storage_3title="Permanent link">¶</a></h3><p>String values are stored as pointers in a <code>basic_json</code> type. That is, for any access to string values, a pointer of type <code>string_t*</code> must be dereferenced.</p><h2id=booleans>Booleans<aclass=headerlinkhref=#booleanstitle="Permanent link">¶</a></h2><p><ahref=https://tools.ietf.org/html/rfc8259>RFC 8259</a> implicitly describes a boolean as a type which differentiates the two literals <code>true</code> and <code>false</code>.</p><h3id=default-type_3>Default type<aclass=headerlinkhref=#default-type_3title="Permanent link">¶</a></h3><p>With the default values for <em>BooleanType</em> (<codeclass=highlight><spanclass=kt>bool</span><spanclass=w></span></code>), the default value for <code>boolean_t</code> is <codeclass=highlight><spanclass=kt>bool</span><spanclass=w></span></code>.</p><h3id=storage_4>Storage<aclass=headerlinkhref=#storage_4title="Permanent link">¶</a></h3><p>Boolean values are stored directly inside a <code>basic_json</code> type.</p><h2id=numbers>Numbers<aclass=headerlinkhref=#numberstitle="Permanent link">¶</a></h2><p>See the <ahref=number_handling/>number handling</a> a
