basic_json::object_t¶
using object_t = ObjectType<StringType,
basic_json,
object_comparator_t,
AllocatorType<std::pair<const StringType, basic_json>>>;
The type used to store JSON objects.
RFC 7159 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 (e.g.,
std::map
orstd::unordered_map
) StringType
- the type of the keys or names (e.g.,
std::string
). The comparison functionstd::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 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,
{"key": 2, "key": 1}
could be equal to either{"key": 1}
or{"key": 2}
. - Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see
dump
) in this order. For instance,{"b": 1, "a": 2}
and{"a": 2, "b": 1}
will be stored and serialized as{"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,
{"b": 1, "a": 2}
and{"a": 2, "b": 1}
will be treated as equal.
Limits¶
RFC 7159 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 is 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 7159, because any order implements the specified "unordered" nature of JSON objects.
Version history¶
- Added in version 1.0.0.