How to Use std::front_inserter in C++

This article explains the purpose, mechanics, and behavior of std::front_inserter in C++. You will learn how this iterator adapter facilitates prepending elements into sequence containers, which containers support it, how it interacts with standard library algorithms, and the critical ordering quirk every developer should be aware of.

What Is std::front_inserter?

Defined in the <iterator> header, std::front_inserter is a convenience function template that creates a std::front_insert_iterator for a given container. Its primary purpose is to allow standard library algorithms (such as std::copy, std::transform, or std::generate_n) to insert new elements at the beginning of a sequence container rather than overwriting existing elements.

When an algorithm assigns a value to a std::front_insert_iterator, the iterator calls the underlying container's push_front() member function. This automatically increases the container's size dynamically without requiring prior memory reservation or resizing.

Compatible Sequence Containers

Because std::front_inserter relies on push_front(), it can only be used with sequence containers that support constant-time element prepending:

  • std::list: A doubly-linked list that provides \(O(1)\) insertions anywhere, including the front.
  • std::forward_list: A singly-linked list designed for forward traversal, offering push_front() natively.
  • std::deque: A double-ended queue that natively supports fast \(O(1)\) insertions at both the front and back.

It cannot be used with std::vector or std::string, because neither provides a push_front() member function due to the performance penalty of shifting all existing elements in contiguous memory.

The Reversal Effect

A defining characteristic of std::front_inserter is that it reverses the order of the source sequence if elements are copied sequentially. Because each consecutive item is inserted at the very beginning of the target container, the last item inserted becomes the first element.

For example, if you copy the sequence {1, 2, 3} into an empty list using std::front_inserter, the insertion order executes as follows:

  1. Insert 1 \(\rightarrow\) {1}
  2. Insert 2 at front \(\rightarrow\) {2, 1}
  3. Insert 3 at front \(\rightarrow\) {3, 2, 1}

The resulting container will hold {3, 2, 1}. If you need to maintain the original sequence order, use std::back_inserter or a standard range-based insert() instead.

Practical Code Example

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

int main() {
    std::vector<int> source = {10, 20, 30, 40, 50};
    std::deque<int> destination;

    // Populate destination by prepending elements
    std::copy(source.begin(), source.end(), std::front_inserter(destination));

    // Output: 50 40 30 20 10
    for (int value : destination) {
        std::cout << value << " ";
    }

    return 0;
}

Summary

std::front_inserter simplifies appending data to the start of a container by bridging standard algorithms with the container’s push_front() method. It eliminates the need for manual loops and explicit resizing, provided the container supports prepending and the resulting reverse order is either desired or accounted for.