C++ std::list::insert

C++ std::list::insert

The std::list::insert function inserts new elements into a std::list at a specified position. It can be used to insert a single element, multiple elements, or elements from a range. This function is highly versatile and allows for flexible modifications of the list’s contents.

---

Syntax of std::list::insert

// 1. Single element
iterator insert(const_iterator position, const value_type& val);
iterator insert(const_iterator position, value_type&& val);

// 2. Fill
iterator insert(const_iterator position, size_type n, const value_type& val);

// 3. Range
template <class InputIterator>
iterator insert(const_iterator position, InputIterator first, InputIterator last);

// 4. Initializer list
iterator insert(const_iterator position, std::initializer_list<value_type> il);

Parameters

Parameter	Description
position	A constant iterator specifying the position in the list where the new element(s) will be inserted.
val	The value of the element(s) to be inserted.
n	The number of elements to insert.
first, last	Iterators defining the range of elements to insert.
il	An initializer list of elements to insert.

Return Value

The function returns an iterator pointing to the first of the newly inserted elements.

Exceptions

The std::list::insert function may throw exceptions in the following cases:

• If memory allocation fails.
• If the copy or move constructor of the element(s) being inserted throws an exception.

The function provides strong exception safety. If an exception occurs, the state of the list remains unchanged.

---

Examples for std::list::insert

Example 1: Inserting a Single Element

This example demonstrates how to use insert to add a single element to a specific position in the list:

Program

#include <iostream>
#include <list>

int main() {
    std::list<int> myList = {10, 20, 30};

    // Insert 15 at the second position
    auto it = myList.insert(++myList.begin(), 15);

    std::cout << "List contents: ";
    for (const auto& elem : myList) {
        std::cout << elem << " ";
    }
    std::cout << std::endl;

    return 0;
}

Explanation:

1. A std::list named myList is initialized with the elements {10, 20, 30}.
2. The insert function is called with ++myList.begin(), which points to the second position in the list.
3. The value 15 is inserted at this position.
4. A range-based for loop iterates through the list and prints its contents.

Output:

List contents: 10 15 20 30

Example 2: Inserting Multiple Elements

This example demonstrates how to use insert to add multiple elements to a list:

Program

#include <iostream>
#include <list>

int main() {
    std::list<int> myList = {10, 20, 30};

    // Insert two elements with value 15 at the second position
    myList.insert(++myList.begin(), 2, 15);

    std::cout << "List contents: ";
    for (const auto& elem : myList) {
        std::cout << elem << " ";
    }
    std::cout << std::endl;

    return 0;
}

Explanation:

1. A std::list named myList is initialized with the elements {10, 20, 30}.
2. The insert function is called with ++myList.begin(), which points to the second position in the list.
3. Two elements, each with the value 15, are inserted at this position.
4. A range-based for loop iterates through the list and prints its contents.

Output:

List contents: 10 15 15 20 30

Example 3: Inserting Elements from a Range

This example demonstrates how to use insert to add elements from another container to a list:

Program

#include <iostream>
#include <list>
#include <vector>

int main() {
    std::list<int> myList = {10, 20, 30};
    std::vector<int> myVector = {40, 50, 60};

    // Insert elements from myVector at the end of myList
    myList.insert(myList.end(), myVector.begin(), myVector.end());

    std::cout << "List contents: ";
    for (const auto& elem : myList) {
        std::cout << elem << " ";
    }
    std::cout << std::endl;

    return 0;
}

Explanation:

1. A std::list named myList is initialized with the elements {10, 20, 30}.
2. A std::vector named myVector is initialized with the elements {40, 50, 60}.
3. The insert function is called with myList.end(), inserting all elements from myVector at the end of myList.
4. A range-based for loop iterates through the list and prints its contents.

Output:

List contents: 10 20 30 40 50 60