json/docs/mkdocs/docs/api/basic_json/object_t.md

nlohmann::basic_json::object_t

using object_t = ObjectType<StringType,
                            basic_json,
                            default_object_comparator_t,
                            AllocatorType<std::pair<const StringType, basic_json>>>;

The type used to store JSON objects.

RFC 8259 describes JSON objects as follows:

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.

To store objects in C++, a type is defined by the template parameters described below.

Template parameters

ObjectType

the container to store objects. Its template parameters must have the same order and meaning as those of std::map; in particular, the third parameter is a comparator. #!cpp std::unordered_map, whose third parameter is a hash function, therefore needs an adapter -- see Template Parameter Requirements for the full list of requirements, an adapter example, and the containers that are known to work.

StringType

the type of the keys or names (e.g., std::string). The comparison function std::less<StringType> is used to order elements inside the container.

AllocatorType

the allocator to use for objects (e.g., std::allocator)

Notes

Default type

With the default values for ObjectType (std::map), StringType (std::string), and AllocatorType (std::allocator), the default value for object_t is:

// until C++14
std::map<
  std::string, // key_type
  basic_json, // value_type
  std::less<std::string>, // key_compare
  std::allocator<std::pair<const std::string, basic_json>> // allocator_type
>

// since C++14
std::map<
  std::string, // key_type
  basic_json, // value_type
  std::less<>, // key_compare
  std::allocator<std::pair<const std::string, basic_json>> // allocator_type
>

See default_object_comparator_t for more information.

Behavior

The choice of object_t influences the behavior of the JSON class. With the default type, objects have the following behavior:

• 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.
• 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, #!json {"key": 2, "key": 1} could be equal to either #!json {"key": 1} or #!json {"key": 2}. To reject duplicate keys instead of silently resolving them one way or another, see this parsing recipe.
• Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see dump) in this order. For instance, #!json {"b": 1, "a": 2} and #!json {"a": 2, "b": 1} will be stored and serialized as #!json {"a": 2, "b": 1}.
• 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, #!json {"b": 1, "a": 2} and #!json {"a": 2, "b": 1} will be treated as equal.

Limits

RFC 8259 specifies:

An implementation may set limits on the maximum depth of nesting.

In this class, the object'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 max_size function of a JSON object.

Storage

Objects are stored as pointers in a basic_json type. That is, for any access to object values, a pointer of type object_t* must be dereferenced.

Object key order

The order name/value pairs are added to the object are not 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 std::map with std::less is used by default. Please note this behavior conforms to RFC 8259, because any order implements the specified "unordered" nature of JSON objects.

Cross-basic_json conversion requirements

When converting an object from one basic_json specialization to another via the converting constructor (overload 4), the target object_t's key_type must be directly constructible from the source basic_json's string_t type (or more generally, from the source object's key type). If this requirement is not met, the conversion does not fail; instead, the object is silently converted as an array of key-value pairs, which is incorrect. See issue #3425 for details and an example.

Examples

??? example

The following code shows that `object_t` is by default, a typedef to `#!cpp std::map<json::string_t, json>`.
 
```cpp
--8<-- "examples/object_t.cpp"
```

Output:

```json
--8<-- "examples/object_t.output"
```

See also

• array_t the type used to store JSON arrays
• string_t the type used to store JSON strings
• object_comparator_t the comparator used to order object keys
• Object Order - the article on object key ordering

Version history

• Added in version 1.0.0.
• Allowed object types whose erase(iterator) returns #!cpp void in version 3.13.0.