# <small>nlohmann::basic_json::</small>emplace_back

```cpp
template<class... Args>
reference emplace_back(Args&& ... args);
```

Creates a JSON value from the passed parameters `args` to the end of the JSON value. If the function is called on a JSON
`#!json null` value, an empty array is created before appending the value created from `args`.

## Template parameters

`Args`
:   compatible types to create a `basic_json` object

## Iterator invalidation

By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the
[`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](end.md)
iterator is invalidated.

## Parameters

`args` (in)
:   arguments to forward to a constructor of `basic_json`

## Return value

reference to the inserted element

## Exception safety

Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `#!json null`
value is converted to an empty array before the element is added and keeps that type if adding the element throws.

## Exceptions

Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON
array or `#!json null`; example: `"cannot use emplace_back() with number"`

## Complexity

Amortized constant.

## Examples

??? example

    The example shows how `emplace_back()` can be used to add elements to a JSON array. Note how the `null` value was
    silently converted to a JSON array.
        
    ```cpp
    #include <iostream>
    #include <nlohmann/json.hpp>
    
    using json = nlohmann::json;
    
    int main()
    {
        // create JSON values
        json array = {1, 2, 3, 4, 5};
        json null;
    
        // print values
        std::cout << array << '\n';
        std::cout << null << '\n';
    
        // add values
        array.emplace_back(6);
        null.emplace_back("first");
        null.emplace_back(3, "second");
    
        // print values
        std::cout << array << '\n';
        std::cout << null << '\n';
    }
    
    ```
    
    Output:
    
    ```json
    [1,2,3,4,5]
    null
    [1,2,3,4,5,6]
    ["first",["second","second","second"]]
    
    ```

## See also

- [operator+=](operator+=.md) add a value to an array/object
- [push_back](push_back.md) add a value to an array/object
- [Modifying values](../../features/modifying_values.md) - the article on modifying values

## Version history

- Since version 2.0.8.
- Returns reference since 3.7.0.