untrusted_input.md did not say that indented dump() and flatten() produce results that grow with the nesting depth times the size of the value (80 KB of input give 600 MB of dump(1)), nor that the binary readers take quadratic time for objects with many keys when they read into ordered_json. Add a warning to "Nesting depth", a section "Objects with many keys in ordered_json", and both points to the checklist. The warning in ordered_map.md still said that parsing JSON text into ordered_json is quadratic; that is no longer true. Name the cases that still are (filling an object key by key, the binary readers) and replace the table with current measurements. dump.md and flatten.md called their complexity linear in the value; it is linear in the result, which can be larger by a factor of the depth. Fixes #6108. Refs #6104. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
1.9 KiB
nlohmann::basic_json::flatten
basic_json flatten() const;
The function creates a JSON object whose keys are JSON pointers (see RFC 6901)
and whose values are all primitive (see is_primitive() for more information). The original JSON
value can be restored using the unflatten() function.
Return value
an object that maps JSON pointers to primitive values
Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
Complexity
Linear in the size of the result. Every key repeats the path of its value, so the keys can be larger than the value by a factor of its nesting depth (see Parsing untrusted input).
Notes
Empty objects and arrays are flattened to #!json null and will not be reconstructed correctly by the
unflatten() function.
Examples
??? example "Example: flatten a JSON object"
The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.
```cpp
--8<-- "examples/flatten.cpp"
```
Output:
```json
--8<-- "examples/flatten.output"
```
??? example "Example: empty objects and arrays are flattened to #!json null"
The following code shows that an empty object and an empty array are both flattened to `#!json null`, and that
`unflatten()` restores them as `#!json null` rather than as empty containers.
```cpp
--8<-- "examples/flatten__empty.cpp"
```
Output:
```json
--8<-- "examples/flatten__empty.output"
```
See also
unflatten- the reverse function- JSON Pointer - the article on JSON Pointer and flattening
Version history
- Added in version 2.0.0.