mirror of
https://github.com/nlohmann/json.git
synced 2026-07-09 12:05:10 +00:00
nlohmann
105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 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](https://tools.ietf.org/html/rfc8259) 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` or `std::unordered_map`)
|
|
|
|
`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`](https://json.nlohmann.me/api/basic_json/default_object_comparator_t/index.md) 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`](https://json.nlohmann.me/api/basic_json/dump/index.md)) 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 8259](https://tools.ietf.org/html/rfc8259) 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`](https://json.nlohmann.me/api/basic_json/max_size/index.md) 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](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
|
|
|
|
## Examples
|
|
|
|
Example
|
|
|
|
The following code shows that `object_t` is by default, a typedef to `std::map<json::string_t, json>`.
|
|
|
|
```
|
|
#include <iostream>
|
|
#include <iomanip>
|
|
#include <nlohmann/json.hpp>
|
|
|
|
using json = nlohmann::json;
|
|
|
|
int main()
|
|
{
|
|
std::cout << std::boolalpha << std::is_same<std::map<json::string_t, json>, json::object_t>::value << std::endl;
|
|
}
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
true
|
|
```
|
|
|
|
## Version history
|
|
|
|
- Added in version 1.0.0.
|