The std::back_inserter Function Template in C++

std::back_inserter adapts a container’s push_back operation into an output iterator. It is useful when an algorithm produces values and the destination should grow as those values are written. The adapter is declared in <iterator>.

The complete programs below are source examples; no run result is asserted here.

How std::back_inserter Works

Include <iterator> and pass the destination container to std::back_inserter. The returned output iterator refers to that container. When an algorithm assigns a value through the iterator, the adapter calls push_back to append the value. It does not point at an existing element or overwrite a slot, so the destination does not need to be pre-sized.

The destination must remain alive while the iterator is used. The adapter stores a reference to it, so do not keep and use the iterator after the container has been destroyed. The function is a convenient way to connect algorithms to containers without writing a loop solely to append each result.

Run this self-contained example to append three copies of 7 after two existing values:

#include <algorithm>
#include <iostream>
#include <iterator>
#include <vector>

int main() {
    std::vector<int> values{10, 20};
    std::fill_n(std::back_inserter(values), 3, 7);

    std::cout << "values:";
    for (int value : values) {
        std::cout << ' ' << value;
    }
    std::cout << '\n';
}

Append Values with std::fill_n

std::fill_n assigns a specified value through an output iterator a specified number of times. With std::back_inserter(values), each assignment appends another value to values; with an iterator into existing storage, assignments would instead replace elements. In the example above, the vector begins with two elements and gains three more, so its final sequence is 10, 20, 7, 7, 7.

The count passed to std::fill_n controls how many assignments it performs. A count of zero performs none. Use a count that is meaningful for the task and representable by the algorithm’s count parameter. The value must be assignable as an element of the destination container. These requirements come from std::fill_n and the container’s element type, not from std::back_inserter itself.

Append Algorithm Output to a Destination Container

Other algorithms can write to the same kind of output iterator. For example, std::set_intersection writes matching values from two sorted ranges into a destination. Its input ranges must be sorted using the ordering used by the algorithm; std::back_inserter does not sort or validate them. The following complete program appends the intersection after an existing value:

#include <algorithm>
#include <iostream>
#include <iterator>
#include <vector>

int main() {
    const std::vector<int> left{1, 2, 4, 6};
    const std::vector<int> right{2, 3, 4, 5};
    std::vector<int> common{99};

    std::set_intersection(left.begin(), left.end(),
                          right.begin(), right.end(),
                          std::back_inserter(common));

    std::cout << "common:";
    for (int value : common) {
        std::cout << ' ' << value;
    }
    std::cout << '\n';
}

Here the two input ranges are already sorted, and the existing 99 remains at the front of the destination; the algorithm appends 2 and 4. The destination is not cleared automatically. Clear it first if the desired result should contain only the newly generated values. Algorithms such as std::copy and std::transform can also use a back inserter when their input and operation meet those algorithms’ requirements.

Requirements and Limitations

std::back_inserter works with containers that provide a suitable push_back operation, including std::vector, std::list, and std::deque. It is not appropriate for containers such as std::set or std::map, which do not expose push_back; use an insertion method or a suitable inserter for those containers. The element supplied by the algorithm must also be accepted by the destination’s push_back.

Appending can cause a container such as std::vector to reallocate as its capacity grows. std::back_inserter does not guarantee fewer reallocations or faster execution. If you know an approximate final size, reserving capacity on a vector may avoid some reallocations, but that is a separate capacity-management choice. The main benefit of the adapter is that algorithms can append results without requiring callers to calculate and provide writable destination positions in advance.