std::forward_list

Introduction

std::forward_list is a container that supports fast insertion and removal of elements from anywhere in the container. Fast random access is not supported. It is implemented as a singly-linked list and essentially does not have any overhead compared to its implementation in C. Compared to std::list this container provides more space efficient storage when bidirectional iteration is not needed.

Remarks

Adding, removing and moving the elements within the list, or across several lists, does not invalidate the iterators currently referring to other elements in the list. However, an iterator or reference referring to an element is invalidated when the corresponding element is removed (via erase_after) from the list. std::forward_list meets the requirements of Container (except for the size member function and that operator=='s complexity is always linear), AllocatorAwareContainer and SequenceContainer.

Example

#include <forward_list>
#include <string>
#include <iostream>

template<typename T>
std::ostream& operator<<(std::ostream& s, const std::forward_list<T>& v) {
    s.put('[');
    char comma[3] = {'\0', ' ', '\0'};
    for (const auto& e : v) {
        s << comma << e;
        comma[0] = ',';
    }
    return s << ']';
}

int main() 
{
    // c++11 initializer list syntax:
    std::forward_list<std::string> words1 {"the", "frogurt", "is", "also", "cursed"};
    std::cout << "words1: " << words1 << '\n';
 
    // words2 == words1
    std::forward_list<std::string> words2(words1.begin(), words1.end());
    std::cout << "words2: " << words2 << '\n';
 
    // words3 == words1
    std::forward_list<std::string> words3(words1);
    std::cout << "words3: " << words3 << '\n';
 
    // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"}
    std::forward_list<std::string> words4(5, "Mo");
    std::cout << "words4: " << words4 << '\n';
}

Output:

words1: [the, frogurt, is, also, cursed]
words2: [the, frogurt, is, also, cursed]
words3: [the, frogurt, is, also, cursed]
words4: [Mo, Mo, Mo, Mo, Mo]

Methods

Method nameDefinition
operator=assigns values to the container
assignassigns values to the container
get_allocatorreturns the associated allocator
------------
Element access
frontaccess the first element
------------
Iterators
before_beginreturns an iterator to the element before beginning
cbefore_beginreturns a constant iterator to the element before beginning
beginreturns an iterator to the beginning
cbeginreturns a const iterator to the beginning
endreturns an iterator to the end
cendreturns a iterator to the end
Capacity
emptychecks whether the container is empty
max_sizereturns the maximum possible number of elements
Modifiers
clearclears the contents
insert_afterinserts elements after an element
emplace_afterconstructs elements in-place after an element
erase_aftererases an element after an element
push_frontinserts an element to the beginning
emplace_frontconstructs an element in-place at the beginning
pop_frontremoves the first element
resizechanges the number of elements stored
swapswaps the contents
Operations
mergemerges two sorted lists
splice_aftermoves elements from another forward_list
removeremoves elements satisfying specific criteria
remove_ifremoves elements satisfying specific criteria
reversereverses the order of the elements
uniqueremoves consecutive duplicate elements
sortsorts the elements


2017-04-13
2017-04-13
C++ Pedia
Icon