lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-29 23:01:16 +03:00
Code Activity

📝 add more API documentation

Browse Source
This commit is contained in:
Niels Lohmann
2020-08-12 14:29:25 +02:00
parent fe89049aee
commit 874f49e945
22 changed files with 285 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
doc/mkdocs/docs/api/basic_json/object_t.md
View File

@ -10,12 +10,10 @@ using object_t = ObjectType<StringType,
The type used to store JSON objects.
[RFC 7159](http://rfc7159.net/rfc7159) 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.
> 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.
To store objects in C++, a type is defined by the template parameters described below.
## Template parameters
@ -23,9 +21,8 @@ described below.
: 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.
: 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`)
@ -34,9 +31,8 @@ described below.
#### Default type
With the default values for `ObjectType` (`std::map`), `StringType`
(`std::string`), and `AllocatorType` (`std::allocator`), the default
value for `object_t` is:
With the default values for `ObjectType` (`std::map`), `StringType` (`std::string`), and `AllocatorType`
(`std::allocator`), the default value for `object_t` is:
```cpp
std::map<
@ -49,23 +45,19 @@ std::map<
#### Behavior
The choice of `object_t` influences the behavior of the JSON class. With
the default type, objects have the following 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
- 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}`.
- Internally, name/value pairs are stored in lexicographical order of the
names. Objects will also be serialized (see [`dump`](dump.md)) in this order.
For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored
- Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see
[`dump`](dump.md)) 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
- 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
@ -73,26 +65,21 @@ the default type, objects have the following behavior:
[RFC 7159](http://rfc7159.net/rfc7159) 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
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`](max_size.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.
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](http://rfc7159.net/rfc7159), because any order implements the
specified "unordered" nature of JSON objects.
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](http://rfc7159.net/rfc7159), because any order implements the specified "unordered" nature of JSON objects.
## Version history