|
◆ basic_json() [5/9]
nlohmann::basic_json::basic_json |
( |
initializer_list_t |
init, |
|
|
bool |
type_deduction = true , |
|
|
value_t |
manual_type = value_t::array |
|
) |
| |
|
inline |
Creates a JSON value of type array or object from the passed initializer list init. In case type_deduction is true (default), the type of the JSON value to be created is deducted from the initializer list init according to the following rules:
- If the list is empty, an empty JSON object value
{} is created.
- If the list consists of pairs whose first element is a string, a JSON object value is created where the first elements of the pairs are treated as keys and the second elements are as values.
- In all other cases, an array is created.
The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
- The empty initializer list is written as
{} which is exactly an empty JSON object.
- C++ has no way of describing mapped types other than to list a list of pairs. As JSON requires that keys must be of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an object.
- In all other cases, the initializer list could not be interpreted as JSON object type, so interpreting it as JSON array type is safe.
With the rules described above, the following JSON values cannot be expressed by an initializer list:
- Note
- When used without parentheses around an empty initializer list, basic_json() is called instead of this function, yielding the JSON null value.
- Parameters
-
[in] | init | initializer list with JSON values |
[in] | type_deduction | internal parameter; when set to true , the type of the JSON value is deducted from the initializer list init; when set to false , the type provided via manual_type is forced. This mode is used by the functions array(initializer_list_t) and object(initializer_list_t). |
[in] | manual_type | internal parameter; when type_deduction is set to false , the created JSON value will use the provided type (only value_t::array and value_t::object are valid); when type_deduction is set to true , this parameter has no effect |
- Exceptions
-
type_error.301 | if type_deduction is false , manual_type is value_t::object , but init contains an element which is not a pair whose first element is a string. In this case, the constructor could not create an object. If type_deduction would have be true , an array would have been created. See object(initializer_list_t) for an example. |
- Complexity
- Linear in the size of the initializer list init.
- Exception safety
- Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
- Example
- The example below shows how JSON values are created from initializer lists.
2 #include <nlohmann/json.hpp>
10 json j_object = { { "one", 1}, { "two", 2} };
11 json j_array = {1, 2, 3, 4};
12 json j_nested_object = { { "one", {1}}, { "two", {1, 2}} };
13 json j_nested_array = { {{1}, "one"}, {{1, 2}, "two"} };
16 std::cout << j_empty_init_list << '\n';
17 std::cout << j_object << '\n';
18 std::cout << j_array << '\n';
19 std::cout << j_nested_object << '\n';
20 std::cout << j_nested_array << '\n';
Output (play with this example online): {}
{"one":1,"two":2}
[1,2,3,4]
{"one":[1],"two":[1,2]}
[[[1],"one"],[[1,2],"two"]]
The example code above can be translated withg++ -std=c++11 -Isingle_include doc/examples/basic_json__list_init_t.cpp -o basic_json__list_init_t
- See also
- array(initializer_list_t) – create a JSON array value from an initializer list
-
object(initializer_list_t) – create a JSON object value from an initializer list
- Since
- version 1.0.0
Definition at line 15999 of file json.hpp.
|