// (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;
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().
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.
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:
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.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.string_t, string literals, and all compatible string containers can be used.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_t / bool can be used.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.
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.
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:
{} is created.The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
#!cpp {} which is exactly an empty JSON object.With the rules described above, the following JSON values cannot be expressed by an initializer list:
#!json []): use array(initializer_list_t) with an empty initializer list in this casearray(initializer_list_t) with the same initializer list in this caseFunction array() and object() force array and object creation from initializer lists, respectively.
Constructs a JSON array value by creating cnt copies of a passed value. In case cnt is 0, an empty array is created.
Constructs the JSON value with the contents of the range [first, last). The semantics depend on the different types a JSON value can have:
#!json null type, invalid_iterator.206 is thrown.first must be begin() and last must be end(). In this case, the value is copied. Otherwise, invalid_iterator.204 is thrown.std::vector or std::map; that is, a JSON array or object is constructed from the values in the range.Creates a copy of a given JSON value.
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.
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.) - `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>
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
to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.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.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.invalid_iterator.204 if iterators first and last belong to a primitive type (number, boolean, or string), but first does not point to the first element anymore. In this case, the range [first, last) is undefined. See the example code below.invalid_iterator.206 if iterators first and last belong to a #!json null value. In this case, the range [first, last) is undefined.val, also depending on the implementation of the called to_json() method.val, also depending on the implementation of the called to_json() method.init.cnt.first and last.other.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 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
??? 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: (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" ```