basic_json unflatten() const;
The function restores the arbitrary nesting of a JSON value that has been flattened before using the flatten() function. The JSON value must meet certain constraints:
the original JSON from a flattened version
Strong exception safety: if an exception occurs, the original value stays intact.
The function can throw the following exceptions:
type_error.314 if value is not an objecttype_error.315 if object values are not primitivetype_error.313 if a key (JSON pointer) leads to a conflicting nesting; example: "invalid value to unflatten"parse_error.106 if an array index in a key begins with ‘0’; example: "array index '01' must not begin with '0'"parse_error.107 if a key is not empty and does not begin with a slash (/); example: "JSON pointer must be empty or begin with '/' - was: 'a'"parse_error.108 if a tilde (~) in a key is not followed by 0 or 1; example: "escape character '~' must be followed with '0' or '1'"parse_error.109 if an array index in a key is not a number; example: "array index 'one' is not a number"out_of_range.404 if a level becomes an array (because one of its keys is 0) and another key at that level begins with a digit but is not a valid array index (such as 1a), or is -; example: "unresolved reference token '-'"Linear in the size of the JSON value.
Empty objects and arrays are flattened by flatten() to #!json null values and cannot unflattened to their original type.
A flattened array and a flattened object whose keys are array indices are indistinguishable, because both are described by the same JSON pointers. A value is therefore restored as an array if and only if one of its keys is the reference token 0, and as an object otherwise: #!json {"2": 1} is restored unchanged, whereas #!json {"0": 1} is restored as #!json [1]. This decision does not depend on the order in which the flattened object is iterated.
Apart from these two cases, for a JSON value j, the following is always true: #!cpp j == j.flatten().unflatten().
??? example
The following code shows how a flattened JSON object is unflattened into the original nested JSON object.
```cpp
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON value
json j_flattened =
{
{"/answer/everything", 42},
{"/happy", true},
{"/list/0", 1},
{"/list/1", 0},
{"/list/2", 2},
{"/name", "Niels"},
{"/nothing", nullptr},
{"/object/currency", "USD"},
{"/object/value", 42.99},
{"/pi", 3.141}
};
// call unflatten()
std::cout << std::setw(4) << j_flattened.unflatten() << '\n';
}
```
Output:
```json
{
"answer": {
"everything": 42
},
"happy": true,
"list": [
1,
0,
2
],
"name": "Niels",
"nothing": null,
"object": {
"currency": "USD",
"value": 42.99
},
"pi": 3.141
}
```
parse_error.109 instead of out_of_range.404 for a one-character array index that is not a digit (e.g., /x) in version 3.13.0, as it already did for longer ones.