【數據結構】STL-list

std::list

template < class T, class Alloc = allocator<T> > class list;
List
Lists are sequence containers that allow constant time insert and erase operations anywhere within the sequence, and iteration in both directions.

List containers are implemented as doubly-linked lists; Doubly linked lists can store each of the elements they contain in different and unrelated storage locations. The ordering is kept internally by the association to each element of a link to the element preceding it and a link to the element following it.

They are very similar to forward_list: The main difference being that forward_list objects are single-linked lists, and thus they can only be iterated forwards, in exchange for being somewhat smaller and more efficient.

Compared to other base standard sequence containers (array, vector and deque), lists perform generally better in inserting, extracting and moving elements in any position within the container for which an iterator has already been obtained, and therefore also in algorithms that make intensive use of these, like sorting algorithms.

The main drawback of lists and forward_lists compared to these other sequence containers is that they lack direct access to the elements by their position; For example, to access the sixth element in a list, one has to iterate from a known position (like the beginning or the end) to that position, which takes linear time in the distance between these. They also consume some extra memory to keep the linking information associated to each element (which may be an important factor for large lists of small-sized elements).

 

Container properties

Sequence
Elements in sequence containers are ordered in a strict linear sequence. Individual elements are accessed by their position in this sequence.
Doubly-linked list
Each element keeps information on how to locate the next and the previous elements, allowing constant time insert and erase operations before or after a specific element (even of entire ranges), but no direct random access.
Allocator-aware
The container uses an allocator object to dynamically handle its storage needs.

 

Template parameters

T
Type of the elements.
Aliased as member type list::value_type.
Alloc
Type of the allocator object used to define the storage allocation model. By default, the allocator class template is used, which defines the simplest memory allocation model and is value-independent.
Aliased as member type list::allocator_type.

 

Member types

member type definition notes
value_type The first template parameter (T)
allocator_type The second template parameter (Alloc) defaults to: allocator<value_type>
reference allocator_type::reference for the default allocator: value_type&
const_reference allocator_type::const_reference for the default allocator: const value_type&
pointer allocator_type::pointer for the default allocator: value_type*
const_pointer allocator_type::const_pointer for the default allocator: const value_type*
iterator a bidirectional iterator to value_type convertible to const_iterator
const_iterator a bidirectional iterator to const value_type
reverse_iterator reverse_iterator<iterator>
const_reverse_iterator reverse_iterator<const_iterator>
difference_type a signed integral type, identical to: iterator_traits<iterator>::difference_type usually the same as ptrdiff_t
size_type an unsigned integral type that can represent any non-negative value of difference_type usually the same as size_t

 

Member functions

Iterators:

Capacity:

Element access:

Modifiers:

Operations:

Observers:

std::list::list

default (1)
explicit list (const allocator_type& alloc = allocator_type());
fill (2)
explicit list (size_type n, const value_type& val = value_type(),
                const allocator_type& alloc = allocator_type());
range (3)
template <class InputIterator>
  list (InputIterator first, InputIterator last,
         const allocator_type& alloc = allocator_type());
copy (4)
list (const list& x);
Construct list
Constructs a list container object, initializing its contents depending on the constructor version used:

(1) empty container constructor (default constructor)
Constructs an empty container, with no elements.
(2) fill constructor
Constructs a container with n elements. Each element is a copy of val.
(3) range constructor
Constructs a container with as many elements as the range [first,last), with each element constructed from its corresponding element in that range, in the same order.
(4) copy constructor
Constructs a container with a copy of each of the elements in x, in the same order.

The container keeps an internal copy of alloc, which is used to allocate storage throughout its lifetime.
The copy constructor (4) creates a container that keeps and uses a copy of x‘s allocator.

The storage for the elements is allocated using this internal allocator.

 

Parameters

alloc
Allocator object.
The container keeps and uses an internal copy of this allocator.
Member type allocator_type is the internal allocator type used by the container, defined in list as an alias of its second template parameter (Alloc).
If allocator_type is an instantiation of the default allocator (which has no state), this is not relevant.
n
Initial container size (i.e., the number of elements in the container at construction).
Member type size_type is an unsigned integral type.
val
Value to fill the container with. Each of the n elements in the container is initialized to a copy of this value.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).
first, last
Input iterators to the initial and final positions in a range. The range used is [first,last), which includes all the elements between first and last, including the element pointed by first but not the element pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed.
x
Another list object of the same type (with the same class template arguments), whose contents are either copied or acquired.
il
An initializer_list object.
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Example

// constructing lists
#include <iostream>
#include <list>

int main ()
{
  // constructors used in the same order as described above:
  std::list<int> first;                                // empty list of ints
  std::list<int> second (4,100);                       // four ints with value 100
  std::list<int> third (second.begin(),second.end());  // iterating through second
  std::list<int> fourth (third);                       // a copy of third

  // the iterator constructor can also be used to construct from arrays:
  int myints[] = {16,2,77,29};
  std::list<int> fifth (myints, myints + sizeof(myints) / sizeof(int) );

  std::cout << "The contents of fifth are: ";
  for (std::list<int>::iterator it = fifth.begin(); it != fifth.end(); it++)
    std::cout << *it << ' ';

  std::cout << '\n';

  return 0;
}

Output:

The contents of fifth are: 16 2 77 29

Complexity

Constant for the default constructor (1), and for the move constructors (5) (unless alloc is different from x‘s allocator).
For all other cases, linear in the number of elements in the resulting container.

std::list::~list

~list();
List destructor
Destroys the container object.

This destroys all container elements, and deallocates all the storage capacity allocated by the list container using its allocator.

Complexity

Linear in list::size (destructors).

public member function
<list>

std::list::operator=

copy (1)
 list& operator= (const list& x);
Assign content
Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.

Copies all the elements from x into the container.

The container preserves its current allocator, which is used to allocate additional storage if needed.

Any elements held in the container before the call are either assigned to or destroyed.

Parameters

x
A list object of the same type (i.e., with the same template parameters, T and Alloc).
il
An initializer_list object. The compiler will automatically construct such objects from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Return value

*this

Example

// assignment operator with lists
#include <iostream>
#include <list>

int main ()
{
  std::list<int> first (3);      // list of 3 zero-initialized ints
  std::list<int> second (5);     // list of 5 zero-initialized ints

  second = first;
  first = std::list<int>();

  std::cout << "Size of first: " << int (first.size()) << '\n';
  std::cout << "Size of second: " << int (second.size()) << '\n';
  return 0;
}

Both list containers of int elements are initialized to sequences with different sizes. Then, second is assigned to first, so both are now equal and with a size of 3. And then, first is assigned to a newly constructed empty container object, so its size is finally 0. Output:

Size of first: 0
Size of second: 3

Complexity

Linear in size.

std::list::begin

      iterator begin();
const_iterator begin() const;
Return iterator to beginning
Returns an iterator pointing to the first element in the list container.

Notice that, unlike member list::front, which returns a reference to the first element, this function returns a bidirectional iterator pointing to it.

If the container is empty, the returned iterator value shall not be dereferenced.

Parameters

none

Return Value

An iterator to the beginning of the sequence container.

If the list object is const-qualified, the function returns a const_iterator. Otherwise, it returns an iterator.

Member types iterator and const_iterator are bidirectional iterator types (pointing to an element and to a const element, respectively).

Example

// list::begin
#include <iostream>
#include <list>

int main ()
{
  int myints[] = {75,23,65,42,13};
  std::list<int> mylist (myints,myints+5);

  std::cout << "mylist contains:";
  for (std::list<int>::iterator it=mylist.begin(); it != mylist.end(); ++it)
    std::cout << ' ' << *it;

  std::cout << '\n';

  return 0;
}

Output:

mylist contains: 75 23 65 42 13

Complexity

Constant.

std::list::end

      iterator end();
const_iterator end() const;
Return iterator to end
Returns an iterator referring to the past-the-end element in the list container.

The past-the-end element is the theoretical element that would follow the last element in the list container. It does not point to any element, and thus shall not be dereferenced.

Because the ranges used by functions of the standard library do not include the element pointed by their closing iterator, this function is often used in combination with list::begin to specify a range including all the elements in the container.

If the container is empty, this function returns the same as list::begin.

Parameters

none

Return Value

An iterator to the element past the end of the sequence.

If the list object is const-qualified, the function returns a const_iterator. Otherwise, it returns an iterator.

Member types iterator and const_iterator are bidirectional iterator types (pointing to an element and to a const element, respectively).

Example

// list::begin/end
#include <iostream>
#include <list>

int main ()
{
  int myints[] = {75,23,65,42,13};
  std::list<int> mylist (myints,myints+5);

  std::cout << "mylist contains:";
  for (std::list<int>::iterator it=mylist.begin() ; it != mylist.end(); ++it)
    std::cout << ' ' << *it;

  std::cout << '\n';

  return 0;
}

Output:

mylist contains: 75 23 65 42 13

Complexity

Constant.

std::list::rbegin

      reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
Return reverse iterator to reverse beginning
Returns a reverse iterator pointing to the last element in the container (i.e., its reverse beginning).

Reverse iterators iterate backwards: increasing them moves them towards the beginning of the container.

rbegin points to the element right before the one that would be pointed to by member end.

Notice that unlike member list::back, which returns a reference to this same element, this function returns a reverse bidirectional iterator.

Parameters

none

Return Value

A reverse iterator to the reverse beginning of the sequence container.

If the list object is const-qualified, the function returns a const_reverse_iterator. Otherwise, it returns a reverse_iterator.

Member types reverse_iterator and const_reverse_iterator are reverse bidirectional iterator types (pointing to an element and to a const element, respectively). See list member types.

Example

// list::rbegin/rend
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  for (int i=1; i<=5; ++i) mylist.push_back(i);

  std::cout << "mylist backwards:";
  for (std::list<int>::reverse_iterator rit=mylist.rbegin(); rit!=mylist.rend(); ++rit)
    std::cout << ' ' << *rit;

  std::cout << '\n';

  return 0;
}

Output:

mylist backwards: 5 4 3 2 1

Complexity

Constant.

std::list::rend

      reverse_iterator rend();
const_reverse_iterator rend() const;
Return reverse iterator to reverse end
Returns a reverse iterator pointing to the theoretical element preceding the first element in the list container (which is considered its reverse end).

The range between list::rbegin and list::rend contains all the elements of the container (in reverse order).

Parameters

none

Return Value

A reverse iterator to the reverse end of the sequence container.

If the list object is const-qualified, the function returns a const_reverse_iterator. Otherwise, it returns a reverse_iterator.

Member types reverse_iterator and const_reverse_iterator are reverse bidirectional iterator types (pointing to an element and to a const element, respectively). See list member types.

Example

// list::rbegin/rend
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  for (int i=1; i<=5; ++i) mylist.push_back(i);

  std::cout << "mylist backwards:";
  for (std::list<int>::reverse_iterator rit=mylist.rbegin(); rit!=mylist.rend(); ++rit)
    std::cout << ' ' << *rit;

  std::cout << '\n';

  return 0;
}

Output:

mylist backwards: 5 4 3 2 1

Complexity

Constant.

std::list::empty

bool empty() const;
Test whether container is empty
Returns whether the list container is empty (i.e. whether its size is 0).

This function does not modify the container in any way. To clear the content of a list container, see list::clear.

Parameters

none

Return Value

true if the container size is 0false otherwise.

Example

// list::empty
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  int sum (0);

  for (int i=1;i<=10;++i) mylist.push_back(i);

  while (!mylist.empty())
  {
     sum += mylist.front();
     mylist.pop_front();
  }

  std::cout << "total: " << sum << '\n';
  
  return 0;
}

The example initializes the content of the container to a sequence of numbers (form 1 to 10). It then pops the elements one by one until it is empty and calculates their sum.

Output:

total: 55

Complexity

Constant.

std::list::size

size_type size() const;
Return size
Returns the number of elements in the list container.

Parameters

none

Return Value

The number of elements in the container.

Member type size_type is an unsigned integral type.

Example

// list::size
#include <iostream>
#include <list>

int main ()
{
  std::list<int> myints;
  std::cout << "0. size: " << myints.size() << '\n';

  for (int i=0; i<10; i++) myints.push_back(i);
  std::cout << "1. size: " << myints.size() << '\n';

  myints.insert (myints.begin(),10,100);
  std::cout << "2. size: " << myints.size() << '\n';

  myints.pop_back();
  std::cout << "3. size: " << myints.size() << '\n';

  return 0;
}

Output:

0. size: 0
1. size: 10
2. size: 20
3. size: 19

Complexity

Up to linear.

std::list::max_size

size_type max_size() const;
Return maximum size
Returns the maximum number of elements that the list container can hold.

This is the maximum potential size the container can reach due to known system or library implementation limitations, but the container is by no means guaranteed to be able to reach that size: it can still fail to allocate storage at any point before that size is reached.

Parameters

none

Return Value

The maximum number of elements the object can hold as content.

Member type size_type is an unsigned integral type.

Example

// list::max_size
#include <iostream>
#include <list>

int main ()
{
  unsigned int i;
  std::list<int> mylist;

  std::cout << "Enter number of elements: ";
  std::cin >> i;

  if (i<mylist.max_size()) mylist.resize(i);
  else std::cout << "That size exceeds the limit.\n";

  return 0;
}

Here, member max_size is used to check beforehand whether the requested size will be allowed by member resize.

Complexity

Up to linear.

std::list::assign

range (1)
template <class InputIterator>
  void assign (InputIterator first, InputIterator last);
fill (2)
void assign (size_type n, const value_type& val);
Assign new content to container
Assigns new contents to the list container, replacing its current contents, and modifying its size accordingly.

In the range version (1), the new contents are elements constructed from each of the elements in the range between first and last, in the same order.

In the fill version (2), the new contents are n elements, each initialized to a copy of val.

Any storage needed for the assigned elements is allocated using the internal allocator.

Any elements held in the container before the call are destroyed and replaced by newly constructed elements (no assignments of elements take place).

Parameters

first, last
Input iterators to the initial and final positions in a sequence. The range used is [first,last), which includes all the elements between first and last, including the element pointed by first but not the element pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed.
n
New size for the container.
Member type size_type is an unsigned integral type.
val
Value to fill the container with. Each of the n elements in the container will be initialized to a copy of this value.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).
il
An initializer_list object. The compiler will automatically construct such objects from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// list::assign
#include <iostream>
#include <list>

int main ()
{
  std::list<int> first;
  std::list<int> second;

  first.assign (7,100);                      // 7 ints with value 100

  second.assign (first.begin(),first.end()); // a copy of first

  int myints[]={1776,7,4};
  first.assign (myints,myints+3);            // assigning from array

  std::cout << "Size of first: " << int (first.size()) << '\n';
  std::cout << "Size of second: " << int (second.size()) << '\n';
  return 0;
}

Output:

Size of first: 3
Size of second: 7

Complexity

Linear in initial and final sizes (destructions, constructions).

std::list::push_front

void push_front (const value_type& val);
Insert element at beginning
Inserts a new element at the beginning of the list, right before its current first element. The content of val is copied (or moved) to the inserted element.

This effectively increases the container size by one.

Parameters

val
Value to be copied (or moved) to the inserted element.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Return value

none

The storage for the new elements is allocated using the container’s allocator, which may throw exceptions on failure (for the default allocatorbad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// list::push_front
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist (2,100);         // two ints with a value of 100
  mylist.push_front (200);
  mylist.push_front (300);

  std::cout << "mylist contains:";
  for (std::list<int>::iterator it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;

  std::cout << '\n';
  return 0;
}

Output:

300 200 100 100 

Complexity

Constant.

std::list::pop_front

void pop_front();
Delete first element
Removes the first element in the list container, effectively reducing its size by one.

This destroys the removed element.

Parameters

none

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// list::pop_front
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  mylist.push_back (100);
  mylist.push_back (200);
  mylist.push_back (300);

  std::cout << "Popping out the elements in mylist:";
  while (!mylist.empty())
  {
    std::cout << ' ' << mylist.front();
    mylist.pop_front();
  }

  std::cout << "\nFinal size of mylist is " << mylist.size() << '\n';

  return 0;
}

Output:

Popping out the elements in mylist: 100 200 300
Final size of mylist is 0

Complexity

Constant.

std::list::push_back

void push_back (const value_type& val);
Add element at the end
Adds a new element at the end of the list container, after its current last element. The content of val is copied (or moved) to the new element.

This effectively increases the container size by one.

Parameters

val
Value to be copied (or moved) to the new element.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Return value

none

The storage for the new elements is allocated using the container’s allocator, which may throw exceptions on failure (for the default allocatorbad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// list::push_back
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  int myint;

  std::cout << "Please enter some integers (enter 0 to end):\n";

  do {
    std::cin >> myint;
    mylist.push_back (myint);
  } while (myint);

  std::cout << "mylist stores " << mylist.size() << " numbers.\n";

  return 0;
}

The example uses push_back to add a new element to the container each time a new integer is read.

Complexity

Constant.

std::list::pop_back

void pop_back();
Delete last element
Removes the last element in the list container, effectively reducing the container size by one.

This destroys the removed element.

Parameters

none

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// list::pop_back
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  int sum (0);
  mylist.push_back (100);
  mylist.push_back (200);
  mylist.push_back (300);

  while (!mylist.empty())
  {
    sum+=mylist.back();
    mylist.pop_back();
  }

  std::cout << "The elements of mylist summed " << sum << '\n';

  return 0;
}

In this example, the elements are popped out from the end of the list after they are added up in the sum. Output:

The elements of mylist summed 600

Complexity

Constant.

std::list::insert

single element (1)
iterator insert (iterator position, const value_type& val);
fill (2)
    void insert (iterator position, size_type n, const value_type& val);
range (3)
template <class InputIterator>
    void insert (iterator position, InputIterator first, InputIterator last);
Insert elements
The container is extended by inserting new elements before the element at the specified position.

This effectively increases the list size by the amount of elements inserted.

Unlike other standard sequence containers, list and forward_list objects are specifically designed to be efficient inserting and removing elements in any position, even in the middle of the sequence.

The arguments determine how many elements are inserted and to which values they are initialized:

Parameters

position
Position in the container where the new elements are inserted.
iterator is a member type, defined as a bidirectional iterator type that points to elements.
val
Value to be copied (or moved) to the inserted elements.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).
n
Number of elements to insert. Each element is initialized to a copy of val.
Member type size_type is an unsigned integral type.
first, last
Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted at position(in the same order).
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed.
il
An initializer_list object. Copies of these elements are inserted at position (in the same order).
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in list as an alias of its first template parameter (T).

Return value

An iterator that points to the first of the newly inserted elements.

Member type iterator is a bidirectional iterator type that points to elements.

The storage for the new elements is allocated using the container’s allocator, which may throw exceptions on failure (for the default allocatorbad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// inserting into a list
#include <iostream>
#include <list>
#include <vector>

int main ()
{
  std::list<int> mylist;
  std::list<int>::iterator it;

  // set some initial values:
  for (int i=1; i<=5; ++i) mylist.push_back(i); // 1 2 3 4 5

  it = mylist.begin();
  ++it;       // it points now to number 2           ^

  mylist.insert (it,10);                        // 1 10 2 3 4 5

  // "it" still points to number 2                      ^
  mylist.insert (it,2,20);                      // 1 10 20 20 2 3 4 5

  --it;       // it points now to the second 20            ^

  std::vector<int> myvector (2,30);
  mylist.insert (it,myvector.begin(),myvector.end());
                                                // 1 10 20 30 30 20 2 3 4 5
                                                //               ^
  std::cout << "mylist contains:";
  for (it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

mylist contains: 1 10 20 30 30 20 2 3 4 5

Complexity

Linear in the number of elements inserted (copy/move construction).

std::list::erase

iterator erase (iterator position);
iterator erase (iterator first, iterator last);
Erase elements
Removes from the list container either a single element (position) or a range of elements ([first,last)).

This effectively reduces the container size by the number of elements removed, which are destroyed.

Unlike other standard sequence containers, list and forward_list objects are specifically designed to be efficient inserting and removing elements in any position, even in the middle of the sequence.

Parameters

position
Iterator pointing to a single element to be removed from the list.
Member types iterator and const_iterator are bidirectional iterator types that point to elements.
first, last
Iterators specifying a range within the list to be removed: [first,last). i.e., the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
Member types iterator and const_iterator are bidirectional iterator types that point to elements.

Return value

An iterator pointing to the element that followed the last element erased by the function call. This is the container endif the operation erased the last element in the sequence.

Member type iterator is a bidirectional iterator type that points to elements.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// erasing from list
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  std::list<int>::iterator it1,it2;

  // set some values:
  for (int i=1; i<10; ++i) mylist.push_back(i*10);

                              // 10 20 30 40 50 60 70 80 90
  it1 = it2 = mylist.begin(); // ^^
  advance (it2,6);            // ^                 ^
  ++it1;                      //    ^              ^

  it1 = mylist.erase (it1);   // 10 30 40 50 60 70 80 90
                              //    ^           ^

  it2 = mylist.erase (it2);   // 10 30 40 50 60 80 90
                              //    ^           ^

  ++it1;                      //       ^        ^
  --it2;                      //       ^     ^

  mylist.erase (it1,it2);     // 10 30 60 80 90
                              //        ^

  std::cout << "mylist contains:";
  for (it1=mylist.begin(); it1!=mylist.end(); ++it1)
    std::cout << ' ' << *it1;
  std::cout << '\n';

  return 0;
}

Output:

mylist contains: 10 30 60 80 90

Complexity

Linear in the number of elements erased (destructions).

std::list::resize

void resize (size_type n, value_type val = value_type());
Change size
Resizes the container so that it contains n elements.

If n is smaller than the current container size, the content is reduced to its first n elements, removing those beyond (and destroying them).

If n is greater than the current container size, the content is expanded by inserting at the end as many elements as needed to reach a size of n. If val is specified, the new elements are initialized as copies of val, otherwise, they are value-initialized.

Notice that this function changes the actual content of the container by inserting or erasing elements from it.

Parameters

n
New container size, expressed in number of elements.
Member type size_type is an unsigned integral type.
val
Object whose content is copied to the added elements in case that n is greater than the current container size.
If not specified, the default constructor is used instead.
Member type value_type is the type of the elements in the container, defined in list as an alias of the first template parameter (T).

Return Value

none

In case of growth, the storage for the new elements is allocated using the container’s allocator, which may throw exceptions on failure (for the default allocatorbad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// resizing list
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;

  // set some initial content:
  for (int i=1; i<10; ++i) mylist.push_back(i);

  mylist.resize(5);
  mylist.resize(8,100);
  mylist.resize(12);

  std::cout << "mylist contains:";
  for (std::list<int>::iterator it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;

  std::cout << '\n';

  return 0;
}

The code sets a sequence of 9 numbers as an initial content for mylist. It then uses resize first to set the container size to 5, then to extend its size to 8 with values of 100 for its new elements, and finally it extends its size to 12 with their default values (for int elements this is zero). Output:

mylist contains: 1 2 3 4 5 100 100 100 0 0 0 0

Complexity

If the container grows, linear in the number number of elements inserted (constructor).
If the container shrinks, linear in the number of elements erased (destructions), plus up to linear in the size (iterator advance).

std::list::clear

void clear();
Clear content
Removes all elements from the list container (which are destroyed), and leaving the container with a size of 0.

Parameters

none

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// clearing lists
#include <iostream>
#include <list>

int main ()
{
  std::list<int> mylist;
  std::list<int>::iterator it;

  mylist.push_back (100);
  mylist.push_back (200);
  mylist.push_back (300);

  std::cout << "mylist contains:";
  for (it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  mylist.clear();
  mylist.push_back (1101);
  mylist.push_back (2202);

  std::cout << "mylist contains:";
  for (it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

mylist contains: 100 200 300
mylist contains: 1101 2202

Complexity

Linear in list::size (destructions).