cppreference.com > C++ Lists assign Syntax:
      #include <list>
      void assign( size_type num, const TYPE& val );
      void assign( input_iterator start, input_iterator end );
The assign() function either gives the current list the values from start to end, or gives it num copies of val. This function will destroy the previous contents of the list. For example, the following code uses assign() to put 10 copies of the integer 42 into a vector:
     vector<int> v;
     v.assign( 10, 42 );
     for( int i = 0; i < v.size(); i++ ) {
       cout << v[i] << " ";
     }
     cout << endl;
The above code displays the following output:
     42 42 42 42 42 42 42 42 42 42
The next example shows how assign() can be used to copy one vector to another:
     vector<int> v1;
     for( int i = 0; i < 10; i++ ) {
       v1.push_back( i );
     }

     vector<int> v2;
     v2.assign( v1.begin(), v1.end() );

     for( int i = 0; i < v2.size(); i++ ) {
       cout << v2[i] << " ";
     }
     cout << endl;
When run, the above code displays the following output:
     0 1 2 3 4 5 6 7 8 9
Related topics: (C++ Strings) assign insert push_back push_front

max_size
Syntax:

      #include <list>
      size_type max_size() const;

The max_size() function returns the maximum number of elements that the list can hold. The max_size() function should not be confused with the size() or (C++ Strings) capacity() functions, which return the number of elements currently in the list and the the number of elements that the list will be able to hold before more memory will have to be allocated, respectively.

Related topics:
size

back
Syntax:

      #include <list>
      TYPE& back();
      const TYPE& back() const;

The back() function returns a reference to the last element in the list.

For example:

     vector<int> v;
     for( int i = 0; i < 5; i++ ) {
       v.push_back(i);
     }
     cout << "The first element is " << v.front()
          << " and the last element is " << v.back() << endl;

This code produces the following output:

     The first element is 0 and the last element is 4

The back() function runs in constant time.

Related topics:
front
pop_back

begin
Syntax:

      #include <list>
      iterator begin();
      const_iterator begin() const;

The function begin() returns an iterator to the first element of the list. begin() should run in constant time.

For example, the following code uses begin() to initialize an iterator that is used to traverse a list:

       // Create a list of characters
       list<char> charList;
       for( int i=0; i < 10; i++ ) {
         charList.push_front( i + 65 );
       }
       // Display the list
       list<char>::iterator theIterator;
       for( theIterator = charList.begin(); theIterator != charList.end(); theIterator++ ) {
         cout << *theIterator;
       }

Related topics:
end
rbegin
rend

clear
Syntax:

      #include <list>
      void clear();

The function clear() deletes all of the elements in the list. clear() runs in linear time.

Related topics:
erase

empty
Syntax:

      #include <list>
      bool empty() const;

The empty() function returns true if the list has no elements, false otherwise.

For example, the following code uses empty() as the stopping condition on a (C/C++ Keywords) while loop to clear a list and display its contents in reverse order:

     vector<int> v;
     for( int i = 0; i < 5; i++ ) {
       v.push_back(i);
     }
     while( !v.empty() ) {
       cout << v.back() << endl;
       v.pop_back();
     }

Related topics:
size

end
Syntax:

      #include <list>
      iterator end();
      const_iterator end() const;

The end() function returns an iterator just past the end of the list.

Note that before you can access the last element of the list using an iterator that you get from a call to end(), you'll have to decrement the iterator first.

For example, the following code uses begin() and end() to iterate through all of the members of a vector:

     vector<int> v1( 5, 789 );
     vector<int>::iterator it;
     for( it = v1.begin(); it != v1.end(); it++ ) {
       cout << *it << endl;
     }

The iterator is initialized with a call to begin(). After the body of the loop has been executed, the iterator is incremented and tested to see if it is equal to the result of calling end(). Since end() returns an iterator pointing to an element just after the last element of the vector, the loop will only stop once all of the elements of the vector have been displayed.

end() runs in constant time.

Related topics:
begin
rbegin
rend

Container constructors & destructors
Syntax:

      container();  container( const container& c );  ~container();

Every list has a default constructor, copy constructor, and destructor.

The default constructor takes no arguments, creates a new instance of that list, and runs in constant time. The default copy constructor runs in linear time and can be used to create a new list that is a copy of the given list c.

The default destructor is called when the list should be destroyed.

For example, the following code creates a pointer to a vector of integers and then uses the default list constructor to allocate a memory for a new vector:

     vector<int>* v;
     v = new vector<int>();

Related topics:
Special container constructors, resize

Container constructors
Syntax:

      #include <list>
      container();
      container( const container& c );
      container( size_type num, const TYPE& val = TYPE() );
      container( input_iterator start, input_iterator end );
      ~container();

The default list constructor takes no arguments, creates a new instance of that list.

The second constructor is a default copy constructor that can be used to create a new list that is a copy of the given list c.

The third constructor creates a list with space for num objects. If val is specified, each of those objects will be given that value. For example, the following code creates a vector consisting of five copies of the integer 42:

     vector<int> v1( 5, 42 );

The last constructor creates a list that is initialized to contain the elements between start and end. For example:

     // create a vector of random integers
     cout << "original vector: ";
     vector<int> v;
     for( int i = 0; i < 10; i++ ) {
       int num = (int) rand() % 10;
       cout << num << " ";
       v.push_back( num );
     }
     cout << endl;

     // find the first element of v that is even
     vector<int>::iterator iter1 = v.begin();
     while( iter1 != v.end() && *iter1 % 2 != 0 ) {
       iter1++;
     }

     // find the last element of v that is even
     vector<int>::iterator iter2 = v.end();
     do {
       iter2--;
     } while( iter2 != v.begin() && *iter2 % 2 != 0 );

     cout << "first even number: " << *iter1 << ", last even number: " << *iter2 << endl;

     cout << "new vector: ";
     vector<int> v2( iter1, iter2 );
     for( int i = 0; i < v2.size(); i++ ) {
       cout << v2[i] << " ";
     }
     cout << endl;

When run, this code displays the following output:

     original vector: 1 9 7 9 2 7 2 1 9 8
     first even number: 2, last even number: 8
     new vector: 2 7 2 1 9

All of these constructors run in linear time except the first, which runs in constant time.

The default destructor is called when the list should be destroyed.

Container operators
Syntax:

      #include <list>
      container operator=(const container& c2);
      bool operator==(const container& c1, const container& c2);
      bool operator!=(const container& c1, const container& c2);
      bool operator<(const container& c1, const container& c2);
      bool operator>(const container& c1, const container& c2);
      bool operator<=(const container& c1, const container& c2);
      bool operator>=(const container& c1, const container& c2);

All of the C++ containers can be compared and assigned with the standard comparison operators: ==, !=, <=, >=, <, >, and =. Performing a comparison or assigning one list to another takes linear time.

Two lists are equal if:

1. Their size is the same, and
2. Each member in location i in one list is equal to the the member in location i in the other list.

Comparisons among lists are done lexicographically.

Related topics:
(C++ Strings) String operators
(C++ Strings) at
merge
unique

erase
Syntax:

      #include <list>
      iterator erase( iterator loc );
      iterator erase( iterator start, iterator end );

The erase() function either deletes the element at location loc, or deletes the elements between start and end (including start but not including end). The return value is the element after the last element erased.

The first version of erase (the version that deletes a single element at location loc) runs in constant time for lists and linear time for vectors, dequeues, and strings. The multiple-element version of erase always takes linear time.

For example:

     // Create a vector, load it with the first ten characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }
     int size = alphaVector.size();
     vector<char>::iterator startIterator;
     vector<char>::iterator tempIterator;
     for( int i=0; i < size; i++ ) {
       startIterator = alphaVector.begin();
       alphaVector.erase( startIterator );
       // Display the vector
       for( tempIterator = alphaVector.begin(); tempIterator != alphaVector.end(); tempIterator++ ) {
         cout << *tempIterator;
       }
       cout << endl;
     }

That code would display the following output:

     BCDEFGHIJ
     CDEFGHIJ
     DEFGHIJ
     EFGHIJ
     FGHIJ
     GHIJ
     HIJ
     IJ
     J

In the next example, erase() is called with two iterators to delete a range of elements from a vector:

     // create a vector, load it with the first ten characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }
     // display the complete vector
     for( int i = 0; i < alphaVector.size(); i++ ) {
       cout << alphaVector[i];
     }
     cout << endl;

     // use erase to remove all but the first two and last three elements
     // of the vector
     alphaVector.erase( alphaVector.begin()+2, alphaVector.end()-3 );
     // display the modified vector
     for( int i = 0; i < alphaVector.size(); i++ ) {
       cout << alphaVector[i];
     }
     cout << endl;

When run, the above code displays:

     ABCDEFGHIJ
     ABHIJ

Related topics:
clear
insert
pop_back
pop_front
remove
remove_if

front
Syntax:

      #include <list>
      TYPE& front();
      const TYPE& front() const;

The front() function returns a reference to the first element of the list, and runs in constant time.

Related topics:
back
pop_front
push_front

insert
Syntax:

      #include <list>
      iterator insert( iterator loc, const TYPE& val );
      void insert( iterator loc, size_type num, const TYPE& val );
      template<TYPE> void insert( iterator loc, input_iterator start, input_iterator end );

The insert() function either:

- inserts val before loc, returning an iterator to the element inserted,
- inserts num copies of val before loc, or
- inserts the elements from start to end before loc.

For example:

     // Create a vector, load it with the first 10 characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }

     // Insert four C's into the vector
     vector<char>::iterator theIterator = alphaVector.begin();
     alphaVector.insert( theIterator, 4, 'C' );

     // Display the vector
     for( theIterator = alphaVector.begin(); theIterator != alphaVector.end(); theIterator++ )    {
       cout << *theIterator;
     }

This code would display:

     CCCCABCDEFGHIJ

Related topics:
assign
erase
merge
push_back
push_front
splice

pop_back
Syntax:

      #include <list>
      void pop_back();

The pop_back() function removes the last element of the list.

pop_back() runs in constant time.

Related topics:
back
erase
pop_front
push_back

merge
Syntax:

      #include <list>
      void merge( list &lst );
      void merge( list &lst, BinPred compfunction );

The function merge() merges the list with lst, producing a combined list that is ordered with respect to the < operator. If compfunction is specified, then it is used as the comparison function for the lists instead of <.

merge() runs in linear time.

Related topics:
Container operators
insert
splice

pop_front
Syntax:

      #include <list>
      void pop_front();

The function pop_front() removes the first element of the list.

The pop_front() function runs in constant time.

Related topics:
erase
front
pop_back
push_front

push_back
Syntax:

      #include <list>
      void push_back( const TYPE& val );

The push_back() function appends val to the end of the list.

For example, the following code puts 10 integers into a list:

       list<int> the_list;
       for( int i = 0; i < 10; i++ )
         the_list.push_back( i );

When displayed, the resulting list would look like this:

     0 1 2 3 4 5 6 7 8 9

push_back() runs in constant time.

Related topics:
assign
insert
pop_back
push_front

push_front
Syntax:

      #include <list>
      void push_front( const TYPE& val );

The push_front() function inserts val at the beginning of list.

push_front() runs in constant time.

Related topics:
assign
front
insert
pop_front
push_back

rbegin
Syntax:

      #include <list>
      reverse_iterator rbegin();
      const_reverse_iterator rbegin() const;

The rbegin() function returns a reverse_iterator to the end of the current list.

rbegin() runs in constant time.

Related topics:
begin
end
rend

remove
Syntax:

      #include <list>
      void remove( const TYPE &val );

The function remove() removes all elements that are equal to val from the list.

For example, the following code creates a list of the first 10 characters of the alphabet, then uses remove() to remove the letter 'E' from the list:

       // Create a list that has the first 10 letters of the alphabet
       list<char> charList;
       for( int i=0; i < 10; i++ )
         charList.push_front( i + 65 );
       // Remove all instances of 'E'
       charList.remove( 'E' );

Remove runs in linear time.

Related topics:
erase
remove_if
unique

remove_if
Syntax:

      #include <list>
      void remove_if( UnPred pr );

The remove_if() function removes all elements from the list for which the unary predicate pr is true.

remove_if() runs in linear time.

Related topics:
erase
remove
unique

rend
Syntax:

      #include <list>
      reverse_iterator rend();
      const_reverse_iterator rend() const;

The function rend() returns a reverse_iterator to the beginning of the current list.

rend() runs in constant time.

Related topics:
begin
end
rbegin

resize
Syntax:

      #include <list>
      void resize( size_type num, const TYPE& val = TYPE() );

The function resize() changes the size of the list to size. If val is specified then any newly-created elements will be initialized to have a value of val.

This function runs in linear time.

Related topics:
(C++ Multimaps) Container constructors & destructors
(C++ Strings) capacity
size

reverse
Syntax:

      #include <list>
      void reverse();

The function reverse() reverses the list, and takes linear time.

Related topics:
sort

size
Syntax:

      #include <list>
      size_type size() const;

The size() function returns the number of elements in the current list.

Related topics:
(C++ Strings) capacity
empty
(C++ Strings) length
max_size
resize

sort
Syntax:

      #include <list>
      void sort();
      void sort( BinPred p );

The sort() function is used to sort lists into ascending order. Ordering is done via the < operator, unless p is specified, in which case it is used to determine if an element is less than another.

Sorting takes N log N time.

Related topics:
reverse

splice
Syntax:

      #include <list>
      void splice( iterator pos, list& lst );
      void splice( iterator pos, list& lst, iterator del );
      void splice( iterator pos, list& lst, iterator start, iterator end );

The splice() function inserts lst at location pos. If specified, the element(s) at del or from start to end are removed.

splice() simply moves elements from one list to another, and doesn't actually do any copying or deleting. Because of this, splice() runs in constant time.

Related topics:
insert
merge
swap

swap
Syntax:

      #include <list>
      void swap( const container& from );

The swap() function exchanges the elements of the current list with those of from. This function operates in constant time.

For example, the following code uses the swap() function to exchange the values of two strings:

       string first( "This comes first" );
       string second( "And this is second" );
       first.swap( second );
       cout << first << endl;
       cout << second << endl;

The above code displays:

       And this is second
       This comes first

Related topics:
splice

assign
Syntax:

      #include <list>
      void assign( size_type num, const TYPE& val );
      void assign( input_iterator start, input_iterator end );

The assign() function either gives the current list the values from start to end, or gives it num copies of val.

This function will destroy the previous contents of the list.

For example, the following code uses assign() to put 10 copies of the integer 42 into a vector:

     vector<int> v;
     v.assign( 10, 42 );
     for( int i = 0; i < v.size(); i++ ) {
       cout << v[i] << " ";
     }
     cout << endl;

The above code displays the following output:

     42 42 42 42 42 42 42 42 42 42

The next example shows how assign() can be used to copy one vector to another:

     vector<int> v1;
     for( int i = 0; i < 10; i++ ) {
       v1.push_back( i );
     }

     vector<int> v2;
     v2.assign( v1.begin(), v1.end() );

     for( int i = 0; i < v2.size(); i++ ) {
       cout << v2[i] << " ";
     }
     cout << endl;

When run, the above code displays the following output:

     0 1 2 3 4 5 6 7 8 9

Related topics:
(C++ Strings) assign
insert
push_back
push_front

back
Syntax:

      #include <list>
      TYPE& back();
      const TYPE& back() const;

The back() function returns a reference to the last element in the list.

For example:

     vector<int> v;
     for( int i = 0; i < 5; i++ ) {
       v.push_back(i);
     }
     cout << "The first element is " << v.front()
          << " and the last element is " << v.back() << endl;

This code produces the following output:

     The first element is 0 and the last element is 4

The back() function runs in constant time.

Related topics:
front
pop_back

begin
Syntax:

      #include <list>
      iterator begin();
      const_iterator begin() const;

The function begin() returns an iterator to the first element of the list. begin() should run in constant time.

For example, the following code uses begin() to initialize an iterator that is used to traverse a list:

       // Create a list of characters
       list<char> charList;
       for( int i=0; i < 10; i++ ) {
         charList.push_front( i + 65 );
       }
       // Display the list
       list<char>::iterator theIterator;
       for( theIterator = charList.begin(); theIterator != charList.end(); theIterator++ ) {
         cout << *theIterator;
       }

Related topics:
end
rbegin
rend

clear
Syntax:

      #include <list>
      void clear();

The function clear() deletes all of the elements in the list. clear() runs in linear time.

Related topics:
erase

Container constructors
Syntax:

      #include <list>
      container();
      container( const container& c );
      container( size_type num, const TYPE& val = TYPE() );
      container( input_iterator start, input_iterator end );
      ~container();

The default list constructor takes no arguments, creates a new instance of that list.

The second constructor is a default copy constructor that can be used to create a new list that is a copy of the given list c.

The third constructor creates a list with space for num objects. If val is specified, each of those objects will be given that value. For example, the following code creates a vector consisting of five copies of the integer 42:

     vector<int> v1( 5, 42 );

The last constructor creates a list that is initialized to contain the elements between start and end. For example:

     // create a vector of random integers
     cout << "original vector: ";
     vector<int> v;
     for( int i = 0; i < 10; i++ ) {
       int num = (int) rand() % 10;
       cout << num << " ";
       v.push_back( num );
     }
     cout << endl;

     // find the first element of v that is even
     vector<int>::iterator iter1 = v.begin();
     while( iter1 != v.end() && *iter1 % 2 != 0 ) {
       iter1++;
     }

     // find the last element of v that is even
     vector<int>::iterator iter2 = v.end();
     do {
       iter2--;
     } while( iter2 != v.begin() && *iter2 % 2 != 0 );

     cout << "first even number: " << *iter1 << ", last even number: " << *iter2 << endl;

     cout << "new vector: ";
     vector<int> v2( iter1, iter2 );
     for( int i = 0; i < v2.size(); i++ ) {
       cout << v2[i] << " ";
     }
     cout << endl;

When run, this code displays the following output:

     original vector: 1 9 7 9 2 7 2 1 9 8
     first even number: 2, last even number: 8
     new vector: 2 7 2 1 9

All of these constructors run in linear time except the first, which runs in constant time.

The default destructor is called when the list should be destroyed.

Container operators
Syntax:

      #include <list>
      container operator=(const container& c2);
      bool operator==(const container& c1, const container& c2);
      bool operator!=(const container& c1, const container& c2);
      bool operator<(const container& c1, const container& c2);
      bool operator>(const container& c1, const container& c2);
      bool operator<=(const container& c1, const container& c2);
      bool operator>=(const container& c1, const container& c2);

All of the C++ containers can be compared and assigned with the standard comparison operators: ==, !=, <=, >=, <, >, and =. Performing a comparison or assigning one list to another takes linear time.

Two lists are equal if:

1. Their size is the same, and
2. Each member in location i in one list is equal to the the member in location i in the other list.

Comparisons among lists are done lexicographically.

Related topics:
(C++ Strings) String operators
(C++ Strings) at
merge
unique

empty
Syntax:

      #include <list>
      bool empty() const;

The empty() function returns true if the list has no elements, false otherwise.

For example, the following code uses empty() as the stopping condition on a (C/C++ Keywords) while loop to clear a list and display its contents in reverse order:

     vector<int> v;
     for( int i = 0; i < 5; i++ ) {
       v.push_back(i);
     }
     while( !v.empty() ) {
       cout << v.back() << endl;
       v.pop_back();
     }

Related topics:
size

end
Syntax:

      #include <list>
      iterator end();
      const_iterator end() const;

The end() function returns an iterator just past the end of the list.

Note that before you can access the last element of the list using an iterator that you get from a call to end(), you'll have to decrement the iterator first.

For example, the following code uses begin() and end() to iterate through all of the members of a vector:

     vector<int> v1( 5, 789 );
     vector<int>::iterator it;
     for( it = v1.begin(); it != v1.end(); it++ ) {
       cout << *it << endl;
     }

The iterator is initialized with a call to begin(). After the body of the loop has been executed, the iterator is incremented and tested to see if it is equal to the result of calling end(). Since end() returns an iterator pointing to an element just after the last element of the vector, the loop will only stop once all of the elements of the vector have been displayed.

end() runs in constant time.

Related topics:
begin
rbegin
rend

erase
Syntax:

      #include <list>
      iterator erase( iterator loc );
      iterator erase( iterator start, iterator end );

The erase() function either deletes the element at location loc, or deletes the elements between start and end (including start but not including end). The return value is the element after the last element erased.

The first version of erase (the version that deletes a single element at location loc) runs in constant time for lists and linear time for vectors, dequeues, and strings. The multiple-element version of erase always takes linear time.

For example:

     // Create a vector, load it with the first ten characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }
     int size = alphaVector.size();
     vector<char>::iterator startIterator;
     vector<char>::iterator tempIterator;
     for( int i=0; i < size; i++ ) {
       startIterator = alphaVector.begin();
       alphaVector.erase( startIterator );
       // Display the vector
       for( tempIterator = alphaVector.begin(); tempIterator != alphaVector.end(); tempIterator++ ) {
         cout << *tempIterator;
       }
       cout << endl;
     }

That code would display the following output:

     BCDEFGHIJ
     CDEFGHIJ
     DEFGHIJ
     EFGHIJ
     FGHIJ
     GHIJ
     HIJ
     IJ
     J

In the next example, erase() is called with two iterators to delete a range of elements from a vector:

     // create a vector, load it with the first ten characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }
     // display the complete vector
     for( int i = 0; i < alphaVector.size(); i++ ) {
       cout << alphaVector[i];
     }
     cout << endl;

     // use erase to remove all but the first two and last three elements
     // of the vector
     alphaVector.erase( alphaVector.begin()+2, alphaVector.end()-3 );
     // display the modified vector
     for( int i = 0; i < alphaVector.size(); i++ ) {
       cout << alphaVector[i];
     }
     cout << endl;

When run, the above code displays:

     ABCDEFGHIJ
     ABHIJ

Related topics:
clear
insert
pop_back
pop_front
remove
remove_if

front
Syntax:

      #include <list>
      TYPE& front();
      const TYPE& front() const;

The front() function returns a reference to the first element of the list, and runs in constant time.

Related topics:
back
pop_front
push_front

insert
Syntax:

      #include <list>
      iterator insert( iterator loc, const TYPE& val );
      void insert( iterator loc, size_type num, const TYPE& val );
      template<TYPE> void insert( iterator loc, input_iterator start, input_iterator end );

The insert() function either:

- inserts val before loc, returning an iterator to the element inserted,
- inserts num copies of val before loc, or
- inserts the elements from start to end before loc.

For example:

     // Create a vector, load it with the first 10 characters of the alphabet
     vector<char> alphaVector;
     for( int i=0; i < 10; i++ ) {
       alphaVector.push_back( i + 65 );
     }

     // Insert four C's into the vector
     vector<char>::iterator theIterator = alphaVector.begin();
     alphaVector.insert( theIterator, 4, 'C' );

     // Display the vector
     for( theIterator = alphaVector.begin(); theIterator != alphaVector.end(); theIterator++ )    {
       cout << *theIterator;
     }

This code would display:

     CCCCABCDEFGHIJ

Related topics:
assign
erase
merge
push_back
push_front
splice

max_size
Syntax:

      #include <list>
      size_type max_size() const;

The max_size() function returns the maximum number of elements that the list can hold. The max_size() function should not be confused with the size() or (C++ Strings) capacity() functions, which return the number of elements currently in the list and the the number of elements that the list will be able to hold before more memory will have to be allocated, respectively.

Related topics:
size

merge
Syntax:

      #include <list>
      void merge( list &lst );
      void merge( list &lst, BinPred compfunction );

The function merge() merges the list with lst, producing a combined list that is ordered with respect to the < operator. If compfunction is specified, then it is used as the comparison function for the lists instead of <.

merge() runs in linear time.

Related topics:
Container operators
insert
splice

pop_back
Syntax:

      #include <list>
      void pop_back();

The pop_back() function removes the last element of the list.

pop_back() runs in constant time.

Related topics:
back
erase
pop_front
push_back

pop_front
Syntax:

      #include <list>
      void pop_front();

The function pop_front() removes the first element of the list.

The pop_front() function runs in constant time.

Related topics:
erase
front
pop_back
push_front

push_back
Syntax:

      #include <list>
      void push_back( const TYPE& val );

The push_back() function appends val to the end of the list.

For example, the following code puts 10 integers into a list:

       list<int> the_list;
       for( int i = 0; i < 10; i++ )
         the_list.push_back( i );

When displayed, the resulting list would look like this:

     0 1 2 3 4 5 6 7 8 9

push_back() runs in constant time.

Related topics:
assign
insert
pop_back
push_front

push_front
Syntax:

      #include <list>
      void push_front( const TYPE& val );

The push_front() function inserts val at the beginning of list.

push_front() runs in constant time.

Related topics:
assign
front
insert
pop_front
push_back

rbegin
Syntax:

      #include <list>
      reverse_iterator rbegin();
      const_reverse_iterator rbegin() const;

The rbegin() function returns a reverse_iterator to the end of the current list.

rbegin() runs in constant time.

Related topics:
begin
end
rend

remove
Syntax:

      #include <list>
      void remove( const TYPE &val );

The function remove() removes all elements that are equal to val from the list.

For example, the following code creates a list of the first 10 characters of the alphabet, then uses remove() to remove the letter 'E' from the list:

       // Create a list that has the first 10 letters of the alphabet
       list<char> charList;
       for( int i=0; i < 10; i++ )
         charList.push_front( i + 65 );
       // Remove all instances of 'E'
       charList.remove( 'E' );

Remove runs in linear time.

Related topics:
erase
remove_if
unique

remove_if
Syntax:

      #include <list>
      void remove_if( UnPred pr );

The remove_if() function removes all elements from the list for which the unary predicate pr is true.

remove_if() runs in linear time.

Related topics:
erase
remove
unique

rend
Syntax:

      #include <list>
      reverse_iterator rend();
      const_reverse_iterator rend() const;

The function rend() returns a reverse_iterator to the beginning of the current list.

rend() runs in constant time.

Related topics:
begin
end
rbegin

resize
Syntax:

      #include <list>
      void resize( size_type num, const TYPE& val = TYPE() );

The function resize() changes the size of the list to size. If val is specified then any newly-created elements will be initialized to have a value of val.

This function runs in linear time.

Related topics:
(C++ Multimaps) Container constructors & destructors
(C++ Strings) capacity
size

reverse
Syntax:

      #include <list>
      void reverse();

The function reverse() reverses the list, and takes linear time.

Related topics:
sort

size
Syntax:

      #include <list>
      size_type size() const;

The size() function returns the number of elements in the current list.

Related topics:
(C++ Strings) capacity
empty
(C++ Strings) length
max_size
resize

sort
Syntax:

      #include <list>
      void sort();
      void sort( BinPred p );

The sort() function is used to sort lists into ascending order. Ordering is done via the < operator, unless p is specified, in which case it is used to determine if an element is less than another.

Sorting takes N log N time.

Related topics:
reverse

splice
Syntax:

      #include <list>
      void splice( iterator pos, list& lst );
      void splice( iterator pos, list& lst, iterator del );
      void splice( iterator pos, list& lst, iterator start, iterator end );

The splice() function inserts lst at location pos. If specified, the element(s) at del or from start to end are removed.

splice() simply moves elements from one list to another, and doesn't actually do any copying or deleting. Because of this, splice() runs in constant time.

Related topics:
insert
merge
swap

swap
Syntax:

      #include <list>
      void swap( const container& from );

The swap() function exchanges the elements of the current list with those of from. This function operates in constant time.

For example, the following code uses the swap() function to exchange the values of two strings:

       string first( "This comes first" );
       string second( "And this is second" );
       first.swap( second );
       cout << first << endl;
       cout << second << endl;

The above code displays:

       And this is second
       This comes first

Related topics:
splice

unique
Syntax:

      #include <list>
      void unique();
      void unique( BinPred pr );

The function unique() removes all consecutive duplicate elements from the list. Note that only consecutive duplicates are removed, which may require that you sort() the list first.

Equality is tested using the == operator, unless pr is specified as a replacement. The ordering of the elements in a list should not change after a call to unique().

unique() runs in linear time.

Related topics:
Container operators
remove
remove_if

unique
Syntax:

      #include <list>
      void unique();
      void unique( BinPred pr );

The function unique() removes all consecutive duplicate elements from the list. Note that only consecutive duplicates are removed, which may require that you sort() the list first.

Equality is tested using the == operator, unless pr is specified as a replacement. The ordering of the elements in a list should not change after a call to unique().

unique() runs in linear time.

Related topics:
Container operators
remove
remove_if