Files
json/docs/mkdocs/docs/api/basic_json/flatten.md
T
Niels Lohmann 38cb5d0573 docs: output growth with nesting depth and ordered_json objects with many keys (#6118)
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>
2026-11-13 17:54:22 +01:00

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

Version history

  • Added in version 2.0.0.