json/docs/mkdocs/docs/api/basic_json/basic_json.md

nlohmann::basic_json::basic_json

// (1)
basic_json(const value_t v);

// (2)
basic_json(std::nullptr_t = nullptr) noexcept;

// (3)
template<typename CompatibleType>
basic_json(CompatibleType&& val) noexcept(noexcept(
           JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),
                                      std::forward<CompatibleType>(val))));

// (4)
template<typename BasicJsonType>
basic_json(const BasicJsonType& val);

// (5)
basic_json(initializer_list_t init,
           bool type_deduction = true,
           value_t manual_type = value_t::array);

// (6)
basic_json(size_type cnt, const basic_json& val);

// (7)
basic_json(iterator first, iterator last);
basic_json(const_iterator first, const_iterator last);

// (8)
basic_json(const basic_json& other);

// (9)
basic_json(basic_json&& other) noexcept;

1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends on the type:

   Value type	initial value
   null	#!json null
   boolean	#!json false
   string	#!json ""
   number	#!json 0
   object	#!json {}
   array	#!json []
   binary	empty array

   The postcondition of this constructor can be restored by calling clear().

2. Create a #!json null JSON value. It either takes a null pointer as parameter (explicitly creating #!json null) or no parameter (implicitly creating #!json null). The passed null pointer itself is not read -- it is only used to choose the right constructor.

3. This is a "catch all" constructor for all compatible JSON types; that is, types for which a to_json() method exists. The constructor forwards the parameter val to that method (to json_serializer<U>::to_json method with U = uncvref_t<CompatibleType>, to be exact).

   Template type CompatibleType includes, but is not limited to, the following types:

   • arrays: array_t and all kinds of compatible containers such as std::vector, std::deque, std::list, std::forward_list, std::array, std::valarray, std::set, std::unordered_set, std::multiset, and std::unordered_multiset with a value_type from which a basic_json value can be constructed.
   • objects: object_t and all kinds of compatible associative containers such as std::map, std::unordered_map, std::multimap, and std::unordered_multimap with a key_type compatible to string_t and a value_type from which a basic_json value can be constructed.
   • strings: string_t, string literals, and all compatible string containers can be used.

   !!! note "Rvalue containers are moved from"

    If `val` is an rvalue of a compatible array-like or object-like container other than `array_t`/`object_t`
    (e.g., `json j = std::move(vec);` or `json j(std::vector<std::string>{...});`), the elements are moved into
    the JSON value instead of copied. Afterwards, the elements of the source container are in a valid but
    unspecified state (**moved-from**). Keys of associative containers are `const` and therefore still copied.
    Lvalues and `const` rvalues are copied, and the source is left unchanged.
   

   • numbers: number_integer_t, number_unsigned_t, number_float_t, and all convertible number types such as int, size_t, int64_t, float or double can be used.
   • boolean: boolean_t / bool can be used.
   • binary: binary_t / std::vector<uint8_t> may be used; unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with const char* will be directed to the string constructor instead. This is both for backwards compatibility and due to the fact that a binary type is not a standard JSON type.

   See the examples below.

4. This is a constructor for existing basic_json types. It does not hijack copy/move constructors, since the parameter has different template arguments than the current ones.

   The constructor tries to convert the internal m_value of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding to_json() overload. For objects and strings, the conversion requires that the target basic_json type's object_t::key_type (or string_t) be directly constructible from the source type's corresponding member type via is_constructible. If this requirement is not met, the conversion does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects as arrays of [key, value] pairs and strings as arrays of character codes. This is a known limitation tracked in issue #3425.

5. Creates a JSON value of type array or object from the passed initializer list init. In case type_deduction is #!cpp true (default), the type of the JSON value to be created is deducted from the initializer list init according to the following rules:

   1. If the list is empty, an empty JSON object value {} is created.
   2. 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.
   3. In all other cases, an array is created.

   The following flowchart also takes into account what happens when type_deduction is #!cpp false, in which case manual_type decides between object and array, and an object can only be forced if init actually matches rule 2 (or is empty):

   flowchart TD
       A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
       B -->|"yes"| C{"type_deduction"}
       B -->|"no"| D{"type_deduction"}
       C -->|"true"| OBJ["create object"]
       C -->|"false"| E{"manual_type"}
       E -->|"object"| OBJ
       E -->|"array"| ARR["create array"]
       D -->|"true"| ARR
       D -->|"false"| F{"manual_type"}
       F -->|"array"| ARR
       F -->|"object"| ERR["throw type_error.301"]
   

   The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:

   1. The empty initializer list is written as #!cpp {} which is exactly an empty JSON object.
   2. 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.
   3. In all other cases, the initializer list could not be interpreted as a JSON object type, so interpreting it as a JSON array type is safe.

   With the rules described above, the following JSON values cannot be expressed by an initializer list:

   • the empty array (#!json []): use array(initializer_list_t) with an empty initializer list in this case
   • arrays whose elements satisfy rule 2: use array(initializer_list_t) with the same initializer list in this case

   Function array() and object() force array and object creation from initializer lists, respectively.

   !!! warning "Brace initialization yields arrays"

    Because this constructor takes an `initializer_list_t`, brace-initializing a `json`/`ordered_json` from
    another `json` value wraps it in a single-element array rather than copying it:
   
    ```cpp
    json j1 = "hello";
    json j2{j1};   // [!] j2 is ["hello"], NOT a copy of j1
    json j3(j1);   // j3 is "hello" -- parentheses copy as expected
    ```
   
    See the FAQ entry on [brace initialization](../../home/faq.md#brace-initialization-yields-arrays) for the
    full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element
    array (`json::array({value})`) if that is what you want.
   

6. Constructs a JSON array value by creating cnt copies of a passed value. In case cnt is 0, an empty array is created.

7. Constructs the JSON value with the contents of the range [first, last). The semantics depend on the different types a JSON value can have:

   • In case of a #!json null type, invalid_iterator.206 is thrown.
   • In case of other primitive types (number, boolean, string, or binary), first must be begin() and last must be end(). In this case, the value is copied. Otherwise, invalid_iterator.204 is thrown.
   • In case of structured types (array, object), the constructor behaves as similar versions for std::vector or std::map; that is, a JSON array or object is constructed from the values in the range.

8. Creates a copy of a given JSON value.

9. Move constructor. Constructs a JSON value with the contents of the given value other using move semantics. It "steals" the resources from other and leaves it as JSON #!json null value.

Template parameters

CompatibleType

a type such that:

• CompatibleType is not derived from std::istream,
• CompatibleType is not basic_json (to avoid hijacking copy/move constructors),
• CompatibleType is not a different basic_json type (i.e. with different template arguments)
• CompatibleType is not a basic_json nested type (e.g., json_pointer, iterator, etc.)
• if JSON_DISABLE_TUPLE_REFERENCE_CONVERSION is defined to 1: CompatibleType is not a one-element std::tuple holding a reference to basic_json
• json_serializer<U> (with U = uncvref_t<CompatibleType>) has a to_json(basic_json_t&, CompatibleType&&) method

BasicJsonType:

a type such that:

• BasicJsonType is a basic_json type.
• BasicJsonType has different template arguments than basic_json_t.

Note: For cross-basic_json conversions to produce correct results, the target basic_json's object_t::key_type and string_t must be directly constructible from the source basic_json's corresponding types. See the description of overload (4) above for details on what happens when this requirement is not met.

U:

uncvref_t<CompatibleType>

Parameters

v (in)

the type of the value to create

val (in)

the value to be forwarded to the respective constructor

init (in)

initializer list with JSON values

type_deduction (in)

internal parameter; when set to #!cpp true, the type of the JSON value is deducted from the initializer list init; when set to #!cpp 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).

manual_type (in)

internal parameter; when type_deduction is set to #!cpp 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 #!cpp true, this parameter has no effect

cnt (in)

the number of JSON copies of val to create

first (in)

the beginning of the range to copy from (included)

last (in)

the end of the range to copy from (excluded)

other (in)

the JSON value to copy/move

Exception safety

1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
2. No-throw guarantee: this constructor never throws exceptions.
3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value. Exception: when val is an rvalue array-like or object-like container, its elements are moved one by one; if an exception is thrown in the middle of the conversion (e.g., an allocation failure), the JSON value is unchanged, but the source container may be left partially moved-from.
4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
9. No-throw guarantee: this constructor never throws exceptions.

Exceptions

1. (none)
2. The function does not throw exceptions.
3. (none)
4. (none)
5. The function can throw the following exceptions:
   • Throws type_error.301 if type_deduction is #!cpp 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 been #!cpp true, an array would have been created. See object(initializer_list_t) for an example.
6. (none)
7. The function can throw the following exceptions:
   • Throws invalid_iterator.201 if iterators first and last are not compatible (i.e., do not belong to the same JSON value). In this case, the range [first, last) is undefined.
   • Throws invalid_iterator.204 if iterators first and last belong to a primitive type (number, boolean, string, or binary), but first does not point to the first element anymore. In this case, the range [first, last) is undefined. See the example code below.
   • Throws invalid_iterator.206 if iterators first and last belong to a #!json null value. In this case, the range [first, last) is undefined.
8. (none)
9. The function does not throw exceptions.

Complexity

1. Constant.
2. Constant.
3. Usually linear in the size of the passed val, also depending on the implementation of the called to_json() method.
4. Usually linear in the size of the passed val, also depending on the implementation of the called to_json() method.
5. Linear in the size of the initializer list init.
6. Linear in cnt.
7. Linear in distance between first and last.
8. Linear in the size of other.
9. Constant.

Notes

• Overload 5:

  !!! note "Empty initializer list"

    When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
    function, yielding the JSON `#!json null` value.
  

• Overload 4:

  !!! info "Implicit conversion"

    The conversion is implicit unless [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md)
    is defined to `0` and `BasicJsonType::string_t` differs from `string_t`. In that case, the constructor is
    `explicit`, so a JSON value with a different string type is no longer silently converted, for example when it is
    passed to a function taking `#!cpp const json&`. Write `#!cpp json(other)` or `#!cpp other.get<json>()` instead.
  

• Overload 7:

  !!! info "Preconditions"

    - Iterators `first` and `last` must be initialized. **This precondition is enforced with a
      [runtime assertion](../../features/assertions.md).
    - Range `[first, last)` is valid. Usually, this precondition cannot be checked efficiently. Only certain edge
      cases are detected; see the description of the exceptions above. A violation of this precondition yields
      undefined behavior.
  

  !!! danger "Runtime assertion"

    A precondition is enforced with a [runtime assertion](../../features/assertions.md).
  

• Overload 8:

  !!! info "Postcondition"

    `#!cpp *this == other`
  

• Overload 9:

  !!! info "Postconditions"

    - `#!cpp `*this` has the same value as `other` before the call.
    - `other` is a JSON `#!json null` value
  

Examples

??? example "Example: (1) create an empty value with a given type"

The following code shows the constructor for different `value_t` values.
 
```cpp
--8<-- "examples/basic_json__value_t.cpp"
```

Output:

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

??? example "Example: (2) create a #!json null object"

The following code shows the constructor with and without a null pointer parameter.
 
```cpp
--8<-- "examples/basic_json__nullptr_t.cpp"
```

Output:

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

??? example "Example: (3) create a JSON value from compatible types"

The following code shows the constructor with several compatible types.
 
```cpp
--8<-- "examples/basic_json__CompatibleType.cpp"
```

Output:

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

Note the output is platform-dependent.

??? example "Example: (4) create a JSON value from another basic_json specialization"

The example below shows how a `json` value is converted to an `ordered_json` value and back using the converting
constructor. Note how the original insertion order of `oj` is not restored, because it was already given up when
converting to `json`, whose `object_t` sorts by key.

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

Output:

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

??? example "Example: (5) create a container (array or object) from an initializer list"

The example below shows how JSON values are created from initializer lists.
 
```cpp
--8<-- "examples/basic_json__list_init_t.cpp"
```

Output:

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

??? example "Example: (6) construct an array with count copies of a given value"

The following code shows examples for creating arrays with several copies of a given value.
 
```cpp
--8<-- "examples/basic_json__size_type_basic_json.cpp"
```

Output:

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

??? example "Example: (7) construct a JSON container given an iterator range"

The example below shows several ways to create JSON values by specifying a subrange with iterators.
 
```cpp
--8<-- "examples/basic_json__InputIt_InputIt.cpp"
```

Output:

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

??? example "Example: (8) copy constructor"

The following code shows an example for the copy constructor.
 
```cpp
--8<-- "examples/basic_json__basic_json.cpp"
```

Output:

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

??? example "Example: (9) move constructor"

The code below shows the move constructor explicitly called via `std::move`.
 
```cpp
--8<-- "examples/basic_json__moveconstructor.cpp"
```

Output:

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

See also

• array create a JSON array value, forcing array creation from an initializer list even when it looks like an object
• object create a JSON object value, forcing object creation from an initializer list
• binary create a JSON binary array value
• operator= copy assignment operator
• Creating JSON values - the article on creating JSON values

Version history

1. Added in version 1.0.0.
2. Added in version 1.0.0.
3. Added in version 2.1.0.
4. Added in version 3.1.2. Explicit for different string types if JSON_USE_IMPLICIT_CONVERSIONS is 0 since version 3.13.0.
5. Added in version 1.0.0.
6. Added in version 1.0.0.
7. Added in version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range that did not cover the whole value (such as (end(), end())) was accepted and the whole binary value was copied, unlike the other primitive types.
8. Added in version 1.0.0.
9. Added in version 1.0.0.