mirror of https://github.com/nlohmann/json.git synced 2026-11-07 08:15:30 +00:00

Files

T

Niels Lohmann f64464daf1 Split the json_view feature page into sub-pages

The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.

The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.

Internal links across the documentation point to the new pages.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-11-02 20:42:55 +01:00

6.2 KiB

Raw Blame History

Creating JSON values

There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text instead, see parsing. A JSON text can also be parsed into a document and read through a view instead of into a value; see Zero-copy JSON views.

From C++ values

Any value of a supported C++ type can be assigned to or used to construct a json:

json j_number  = 42;
json j_float   = 3.141;
json j_string  = "Hello";
json j_boolean = true;
json j_null    = nullptr;
json j_vector  = std::vector<int>{1, 2, 3};   // array

See converting values for the full set of supported types.

With initializer lists

Objects and arrays can be written concisely with brace-enclosed initializer lists:

// an array
json array = {1, 2, 3, 4};

// an object (a list of key/value pairs)
json object = {
    {"pi", 3.141},
    {"happy", true},
    {"name", "Niels"},
    {"nothing", nullptr},
    {"list", {1, 0, 2}},
    {"object", {{"currency", "USD"}, {"value", 42.99}}}
};

The library decides between an array and an object based on the content: a list whose elements are all two-element lists with a string as the first element is treated as an object, everything else as an array.

!!! warning "Ambiguous cases: #!cpp {} vs. #!cpp []"

Because the same `#!cpp {}` syntax is used for both arrays and objects, some cases are ambiguous. To force a
particular type, use the explicit factory functions [`json::array`](../api/basic_json/array.md) and
[`json::object`](../api/basic_json/object.md):

```cpp
json empty_array_explicit = json::array();               // []
json empty_object_explicit = json::object();             // {}

// a JSON array with one object, not an object with one member
json array_of_objects = json::array({{"key", "value"}}); // [{"key":"value"}]
```

Related to this, single-element brace initialization such as `#!cpp json j{value};` wraps the element in a
single-element **array** by default, and its behavior even differs between compilers. See the
[FAQ](../home/faq.md#brace-initialization-yields-arrays) for details and the opt-in
[`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md) macro.

What does this produce?

The following table shows how some common spellings are interpreted. When in doubt, use #!cpp json::array(), #!cpp json::object(), or the #!cpp json(value) form with parentheses.

code	result	note
`#!cpp json j = {};` / `#!cpp json j{};`	`#!json null`	use `json::object()` or `json::array()`
`#!cpp json j = json::object();`	`#!json {}`
`#!cpp json j = json::array();`	`#!json []`
`#!cpp json j(true);`	`#!json true`	parentheses create the value itself
`#!cpp json j = {true};`	`#!json [true]`	braces create a one-element array (`#!cpp json j{true};` depends on the compiler, see the FAQ)
`#!cpp json j = {{"a", 1}};`	`#!json {"a":1}`	all elements are `[string, value]` pairs: object
`#!cpp json j = {{"a", 1}, {"b"}};`	`#!json [["a",1],["b"]]`	one element is not a pair: array
`#!cpp json j = {{"a", 1}, 2};`	`#!json [["a",1],2]`	a plain value among pairs: array
`#!cpp json j = {{"a", 1, 2}};`	`#!json [["a",1,2]]`	a three-element list is not a pair: array
`#!cpp json j = "{\"a\":1}";`	`#!json "{\"a\":1}"`	a string value; it is not parsed
`#!cpp json j = json::parse("{\"a\":1}");`	`#!json {"a":1}`	parse text with `parse` or `_json`

Building incrementally

A value can also be built up piece by piece. Accessing a non-existing object key or array index with operator[] creates the element on the fly:

json j;                    // null
j["answer"]["everything"] = 42;   // becomes an object
j["list"] = {1, 0, 2};
j["list"].push_back(3);           // [1,0,2,3]

See modifying values for push_back, emplace, and related functions.

With the `_json` literal

The _json user-defined literal parses a string at the call site and is a convenient way to write a JSON value inline:

??? example

```cpp
--8<-- "examples/operator_literal_json.cpp"
```

Output:

```json
--8<-- "examples/operator_literal_json.output"
```

Note this parses the string, so #!cpp "42"_json is the number #!cpp 42, whereas #!cpp json("42") is the JSON string #!json "42".

6.2 KiB Raw Blame History